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 `channel_id` of the channel which has been closed.
78 public final org.ldk.structs.ChannelId channel_id;
80 * Counterparty in the closed channel.
82 public final byte[] counterparty_node_id;
84 * The unique identifier for the claim of the anchor output in the commitment transaction.
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.
90 public final byte[] claim_id;
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.
95 public final int package_target_feerate_sat_per_1000_weight;
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
101 public final byte[] commitment_tx;
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.
106 public final long commitment_tx_fee_satoshis;
108 * The descriptor to sign the anchor input of the anchor transaction constructed as a
109 * result of consuming this event.
111 public final org.ldk.structs.AnchorDescriptor anchor_descriptor;
113 * The set of pending HTLCs on the commitment transaction that need to be resolved once the
114 * commitment transaction confirms.
116 public final HTLCOutputInCommitment[] pending_htlcs;
117 private ChannelClose(long ptr, bindings.LDKBumpTransactionEvent.ChannelClose obj) {
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;
141 this.pending_htlcs = pending_htlcs_conv_24_arr;
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.
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
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.
172 * [`EcdsaChannelSigner`]: crate::sign::ecdsa::EcdsaChannelSigner
173 * [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::sign::ecdsa::EcdsaChannelSigner::sign_holder_htlc_transaction
175 public final static class HTLCResolution extends BumpTransactionEvent {
177 * The `channel_id` of the channel which has been closed.
179 public final org.ldk.structs.ChannelId channel_id;
181 * Counterparty in the closed channel.
183 public final byte[] counterparty_node_id;
185 * The unique identifier for the claim of the HTLCs in the confirmed commitment
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.
192 public final byte[] claim_id;
194 * The target feerate that the resulting HTLC transaction must meet.
196 public final int target_feerate_sat_per_1000_weight;
198 * The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably
199 * by the same transaction.
201 public final HTLCDescriptor[] htlc_descriptors;
203 * The locktime required for the resulting HTLC transaction.
205 public final int tx_lock_time;
206 private HTLCResolution(long ptr, bindings.LDKBumpTransactionEvent.HTLCResolution obj) {
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;
224 this.htlc_descriptors = htlc_descriptors_conv_16_arr;
225 this.tx_lock_time = obj.tx_lock_time;
229 long ret = bindings.BumpTransactionEvent_clone_ptr(this.ptr);
230 Reference.reachabilityFence(this);
235 * Creates a copy of the BumpTransactionEvent
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); };
247 * Utility method to constructs a new ChannelClose-variant BumpTransactionEvent
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); }; };
269 * Utility method to constructs a new HTLCResolution-variant BumpTransactionEvent
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); }; };
288 * Checks if two BumpTransactionEvents contain equal inner contents.
289 * This ignores pointers and is_owned flags and looks at the values in fields.
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);
298 @Override public boolean equals(Object o) {
299 if (!(o instanceof BumpTransactionEvent)) return false;
300 return this.eq((BumpTransactionEvent)o);