1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import javax.annotation.Nullable;
10 * A trait to sign lightning channel transactions as described in BOLT 3.
12 * Signing services could be implemented on a hardware wallet. In this case,
13 * the current Sign would be a front-end on top of a communication
14 * channel connected to your secure device and lightning key material wouldn't
15 * reside on a hot server. Nevertheless, a this deployment would still need
16 * to trust the ChannelManager to avoid loss of funds as this latest component
17 * could ask to sign commitment transaction with HTLCs paying to attacker pubkeys.
19 * A more secure iteration would be to use hashlock (or payment points) to pair
20 * invoice/incoming HTLCs with outgoing HTLCs to implement a no-trust-ChannelManager
21 * at the price of more state and computation on the hardware wallet side. In the future,
22 * we are looking forward to design such interface.
24 * In any case, ChannelMonitor or fallback watchtowers are always going to be trusted
25 * to act, as liveness and breach reply correctness are always going to be hard requirements
26 * of LN security model, orthogonal of key management issues.
28 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
29 public class BaseSign extends CommonBase {
30 final bindings.LDKBaseSign bindings_instance;
31 BaseSign(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
32 private BaseSign(bindings.LDKBaseSign arg, ChannelPublicKeys pubkeys) {
33 super(bindings.LDKBaseSign_new(arg, pubkeys == null ? 0 : pubkeys.clone_ptr()));
34 this.ptrs_to.add(arg);
35 this.bindings_instance = arg;
37 @Override @SuppressWarnings("deprecation")
38 protected void finalize() throws Throwable {
39 if (ptr != 0) { bindings.BaseSign_free(ptr); } super.finalize();
42 public static interface BaseSignInterface {
44 * Gets the per-commitment point for a specific commitment number
46 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
48 byte[] get_per_commitment_point(long idx);
50 * Gets the commitment secret for a specific commitment number as part of the revocation process
52 * An external signer implementation should error here if the commitment was already signed
53 * and should refuse to sign it in the future.
55 * May be called more than once for the same index.
57 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
59 byte[] release_commitment_secret(long idx);
61 * Validate the counterparty's signatures on the holder commitment transaction and HTLCs.
63 * This is required in order for the signer to make sure that releasing a commitment
64 * secret won't leave us without a broadcastable holder transaction.
65 * Policy checks should be implemented in this function, including checking the amount
66 * sent to us and checking the HTLCs.
68 Result_NoneNoneZ validate_holder_commitment(HolderCommitmentTransaction holder_tx);
70 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
71 * some SpendableOutputDescriptor types. This should be sufficient to identify this
72 * Sign object uniquely and lookup or re-derive its keys.
74 byte[] channel_keys_id();
76 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
78 * Note that if signing fails or is rejected, the channel will be force-closed.
80 * Policy checks should be implemented in this function, including checking the amount
81 * sent to us and checking the HTLCs.
83 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx);
85 * Validate the counterparty's revocation.
87 * This is required in order for the signer to make sure that the state has moved
88 * forward and it is safe to sign the next counterparty commitment.
90 Result_NoneNoneZ validate_counterparty_revocation(long idx, byte[] secret);
92 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
93 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
94 * latest commitment_tx when we initiate a force-close.
95 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
96 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
98 * This may be called multiple times for the same transaction.
100 * An external signer implementation should check that the commitment has not been revoked.
102 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
104 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx);
106 * Create a signature for the given input in a transaction spending an HTLC transaction output
107 * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
109 * A justice transaction may claim multiple outputs at the same time if timelocks are
110 * similar, but only a signature for the input at index `input` should be signed for here.
111 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
112 * to an upcoming timelock expiration.
114 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
116 * per_commitment_key is revocation secret which was provided by our counterparty when they
117 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
118 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
121 Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key);
123 * Create a signature for the given input in a transaction spending a commitment transaction
124 * HTLC output when our counterparty broadcasts an old state.
126 * A justice transaction may claim multiple outputs at the same time if timelocks are
127 * similar, but only a signature for the input at index `input` should be signed for here.
128 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
129 * to an upcoming timelock expiration.
131 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
133 * per_commitment_key is revocation secret which was provided by our counterparty when they
134 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
135 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
138 * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
139 * (which is committed to in the BIP 143 signatures).
141 Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc);
143 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
144 * transaction, either offered or received.
146 * Such a transaction may claim multiples offered outputs at same time if we know the
147 * preimage for each when we create it, but only the input at index `input` should be
148 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
149 * needed with regards to an upcoming timelock expiration.
151 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
154 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
156 * Per_commitment_point is the dynamic point corresponding to the channel state
157 * detected onchain. It has been generated by our counterparty and is used to derive
158 * channel state keys, which are then included in the witness script and committed to in the
161 Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc);
163 * Create a signature for a (proposed) closing transaction.
165 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
166 * chosen to forgo their output as dust.
168 Result_SignatureNoneZ sign_closing_transaction(ClosingTransaction closing_tx);
170 * Signs a channel announcement message with our funding key, proving it comes from one
171 * of the channel participants.
173 * Note that if this fails or is rejected, the channel will not be publicly announced and
174 * our counterparty may (though likely will not) close the channel on us for violating the
177 Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg);
179 * Set the counterparty static channel data, including basepoints,
180 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
181 * This is done as soon as the funding outpoint is known. Since these are static channel data,
182 * they MUST NOT be allowed to change to different values once set.
184 * channel_parameters.is_populated() MUST be true.
186 * We bind holder_selected_contest_delay late here for API convenience.
188 * Will be called before any signatures are applied.
190 void ready_channel(ChannelTransactionParameters channel_parameters);
192 private static class LDKBaseSignHolder { BaseSign held; }
193 public static BaseSign new_impl(BaseSignInterface arg, ChannelPublicKeys pubkeys) {
194 final LDKBaseSignHolder impl_holder = new LDKBaseSignHolder();
195 impl_holder.held = new BaseSign(new bindings.LDKBaseSign() {
196 @Override public byte[] get_per_commitment_point(long idx) {
197 byte[] ret = arg.get_per_commitment_point(idx);
198 byte[] result = InternalUtils.check_arr_len(ret, 33);
201 @Override public byte[] release_commitment_secret(long idx) {
202 byte[] ret = arg.release_commitment_secret(idx);
203 byte[] result = InternalUtils.check_arr_len(ret, 32);
206 @Override public long validate_holder_commitment(long holder_tx) {
207 HolderCommitmentTransaction holder_tx_hu_conv = null; if (holder_tx < 0 || holder_tx > 4096) { holder_tx_hu_conv = new HolderCommitmentTransaction(null, holder_tx); }
208 Result_NoneNoneZ ret = arg.validate_holder_commitment(holder_tx_hu_conv);
209 long result = ret == null ? 0 : ret.clone_ptr();
212 @Override public byte[] channel_keys_id() {
213 byte[] ret = arg.channel_keys_id();
214 byte[] result = InternalUtils.check_arr_len(ret, 32);
217 @Override public long sign_counterparty_commitment(long commitment_tx) {
218 CommitmentTransaction commitment_tx_hu_conv = null; if (commitment_tx < 0 || commitment_tx > 4096) { commitment_tx_hu_conv = new CommitmentTransaction(null, commitment_tx); }
219 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_counterparty_commitment(commitment_tx_hu_conv);
220 long result = ret == null ? 0 : ret.clone_ptr();
223 @Override public long validate_counterparty_revocation(long idx, byte[] secret) {
224 Result_NoneNoneZ ret = arg.validate_counterparty_revocation(idx, secret);
225 long result = ret == null ? 0 : ret.clone_ptr();
228 @Override public long sign_holder_commitment_and_htlcs(long commitment_tx) {
229 HolderCommitmentTransaction commitment_tx_hu_conv = null; if (commitment_tx < 0 || commitment_tx > 4096) { commitment_tx_hu_conv = new HolderCommitmentTransaction(null, commitment_tx); }
230 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_holder_commitment_and_htlcs(commitment_tx_hu_conv);
231 long result = ret == null ? 0 : ret.clone_ptr();
234 @Override public long sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
235 Result_SignatureNoneZ ret = arg.sign_justice_revoked_output(justice_tx, input, amount, per_commitment_key);
236 long result = ret == null ? 0 : ret.clone_ptr();
239 @Override public long sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, long htlc) {
240 HTLCOutputInCommitment htlc_hu_conv = null; if (htlc < 0 || htlc > 4096) { htlc_hu_conv = new HTLCOutputInCommitment(null, htlc); }
241 Result_SignatureNoneZ ret = arg.sign_justice_revoked_htlc(justice_tx, input, amount, per_commitment_key, htlc_hu_conv);
242 long result = ret == null ? 0 : ret.clone_ptr();
245 @Override public long sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, long htlc) {
246 HTLCOutputInCommitment htlc_hu_conv = null; if (htlc < 0 || htlc > 4096) { htlc_hu_conv = new HTLCOutputInCommitment(null, htlc); }
247 Result_SignatureNoneZ ret = arg.sign_counterparty_htlc_transaction(htlc_tx, input, amount, per_commitment_point, htlc_hu_conv);
248 long result = ret == null ? 0 : ret.clone_ptr();
251 @Override public long sign_closing_transaction(long closing_tx) {
252 ClosingTransaction closing_tx_hu_conv = null; if (closing_tx < 0 || closing_tx > 4096) { closing_tx_hu_conv = new ClosingTransaction(null, closing_tx); }
253 Result_SignatureNoneZ ret = arg.sign_closing_transaction(closing_tx_hu_conv);
254 long result = ret == null ? 0 : ret.clone_ptr();
257 @Override public long sign_channel_announcement(long msg) {
258 UnsignedChannelAnnouncement msg_hu_conv = null; if (msg < 0 || msg > 4096) { msg_hu_conv = new UnsignedChannelAnnouncement(null, msg); }
259 Result_SignatureNoneZ ret = arg.sign_channel_announcement(msg_hu_conv);
260 long result = ret == null ? 0 : ret.clone_ptr();
263 @Override public void ready_channel(long channel_parameters) {
264 ChannelTransactionParameters channel_parameters_hu_conv = null; if (channel_parameters < 0 || channel_parameters > 4096) { channel_parameters_hu_conv = new ChannelTransactionParameters(null, channel_parameters); }
265 arg.ready_channel(channel_parameters_hu_conv);
268 return impl_holder.held;
271 * Gets the per-commitment point for a specific commitment number
273 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
275 public byte[] get_per_commitment_point(long idx) {
276 byte[] ret = bindings.BaseSign_get_per_commitment_point(this.ptr, idx);
281 * Gets the commitment secret for a specific commitment number as part of the revocation process
283 * An external signer implementation should error here if the commitment was already signed
284 * and should refuse to sign it in the future.
286 * May be called more than once for the same index.
288 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
290 public byte[] release_commitment_secret(long idx) {
291 byte[] ret = bindings.BaseSign_release_commitment_secret(this.ptr, idx);
296 * Validate the counterparty's signatures on the holder commitment transaction and HTLCs.
298 * This is required in order for the signer to make sure that releasing a commitment
299 * secret won't leave us without a broadcastable holder transaction.
300 * Policy checks should be implemented in this function, including checking the amount
301 * sent to us and checking the HTLCs.
303 public Result_NoneNoneZ validate_holder_commitment(HolderCommitmentTransaction holder_tx) {
304 long ret = bindings.BaseSign_validate_holder_commitment(this.ptr, holder_tx == null ? 0 : holder_tx.ptr & ~1);
305 if (ret >= 0 && ret <= 4096) { return null; }
306 Result_NoneNoneZ ret_hu_conv = Result_NoneNoneZ.constr_from_ptr(ret);
307 this.ptrs_to.add(holder_tx);
312 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
313 * some SpendableOutputDescriptor types. This should be sufficient to identify this
314 * Sign object uniquely and lookup or re-derive its keys.
316 public byte[] channel_keys_id() {
317 byte[] ret = bindings.BaseSign_channel_keys_id(this.ptr);
322 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
324 * Note that if signing fails or is rejected, the channel will be force-closed.
326 * Policy checks should be implemented in this function, including checking the amount
327 * sent to us and checking the HTLCs.
329 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx) {
330 long ret = bindings.BaseSign_sign_counterparty_commitment(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
331 if (ret >= 0 && ret <= 4096) { return null; }
332 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
333 this.ptrs_to.add(commitment_tx);
338 * Validate the counterparty's revocation.
340 * This is required in order for the signer to make sure that the state has moved
341 * forward and it is safe to sign the next counterparty commitment.
343 public Result_NoneNoneZ validate_counterparty_revocation(long idx, byte[] secret) {
344 long ret = bindings.BaseSign_validate_counterparty_revocation(this.ptr, idx, InternalUtils.check_arr_len(secret, 32));
345 if (ret >= 0 && ret <= 4096) { return null; }
346 Result_NoneNoneZ ret_hu_conv = Result_NoneNoneZ.constr_from_ptr(ret);
351 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
352 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
353 * latest commitment_tx when we initiate a force-close.
354 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
355 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
357 * This may be called multiple times for the same transaction.
359 * An external signer implementation should check that the commitment has not been revoked.
361 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
363 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx) {
364 long ret = bindings.BaseSign_sign_holder_commitment_and_htlcs(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
365 if (ret >= 0 && ret <= 4096) { return null; }
366 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
367 this.ptrs_to.add(commitment_tx);
372 * Create a signature for the given input in a transaction spending an HTLC transaction output
373 * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
375 * A justice transaction may claim multiple outputs at the same time if timelocks are
376 * similar, but only a signature for the input at index `input` should be signed for here.
377 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
378 * to an upcoming timelock expiration.
380 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
382 * per_commitment_key is revocation secret which was provided by our counterparty when they
383 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
384 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
387 public Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
388 long ret = bindings.BaseSign_sign_justice_revoked_output(this.ptr, justice_tx, input, amount, InternalUtils.check_arr_len(per_commitment_key, 32));
389 if (ret >= 0 && ret <= 4096) { return null; }
390 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
395 * Create a signature for the given input in a transaction spending a commitment transaction
396 * HTLC output when our counterparty broadcasts an old state.
398 * A justice transaction may claim multiple outputs at the same time if timelocks are
399 * similar, but only a signature for the input at index `input` should be signed for here.
400 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
401 * to an upcoming timelock expiration.
403 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
405 * per_commitment_key is revocation secret which was provided by our counterparty when they
406 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
407 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
410 * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
411 * (which is committed to in the BIP 143 signatures).
413 public Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc) {
414 long ret = bindings.BaseSign_sign_justice_revoked_htlc(this.ptr, justice_tx, input, amount, InternalUtils.check_arr_len(per_commitment_key, 32), htlc == null ? 0 : htlc.ptr & ~1);
415 if (ret >= 0 && ret <= 4096) { return null; }
416 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
417 this.ptrs_to.add(htlc);
422 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
423 * transaction, either offered or received.
425 * Such a transaction may claim multiples offered outputs at same time if we know the
426 * preimage for each when we create it, but only the input at index `input` should be
427 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
428 * needed with regards to an upcoming timelock expiration.
430 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
433 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
435 * Per_commitment_point is the dynamic point corresponding to the channel state
436 * detected onchain. It has been generated by our counterparty and is used to derive
437 * channel state keys, which are then included in the witness script and committed to in the
440 public Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc) {
441 long ret = bindings.BaseSign_sign_counterparty_htlc_transaction(this.ptr, htlc_tx, input, amount, InternalUtils.check_arr_len(per_commitment_point, 33), htlc == null ? 0 : htlc.ptr & ~1);
442 if (ret >= 0 && ret <= 4096) { return null; }
443 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
444 this.ptrs_to.add(htlc);
449 * Create a signature for a (proposed) closing transaction.
451 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
452 * chosen to forgo their output as dust.
454 public Result_SignatureNoneZ sign_closing_transaction(ClosingTransaction closing_tx) {
455 long ret = bindings.BaseSign_sign_closing_transaction(this.ptr, closing_tx == null ? 0 : closing_tx.ptr & ~1);
456 if (ret >= 0 && ret <= 4096) { return null; }
457 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
458 this.ptrs_to.add(closing_tx);
463 * Signs a channel announcement message with our funding key, proving it comes from one
464 * of the channel participants.
466 * Note that if this fails or is rejected, the channel will not be publicly announced and
467 * our counterparty may (though likely will not) close the channel on us for violating the
470 public Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg) {
471 long ret = bindings.BaseSign_sign_channel_announcement(this.ptr, msg == null ? 0 : msg.ptr & ~1);
472 if (ret >= 0 && ret <= 4096) { return null; }
473 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
474 this.ptrs_to.add(msg);
479 * Set the counterparty static channel data, including basepoints,
480 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
481 * This is done as soon as the funding outpoint is known. Since these are static channel data,
482 * they MUST NOT be allowed to change to different values once set.
484 * channel_parameters.is_populated() MUST be true.
486 * We bind holder_selected_contest_delay late here for API convenience.
488 * Will be called before any signatures are applied.
490 public void ready_channel(ChannelTransactionParameters channel_parameters) {
491 bindings.BaseSign_ready_channel(this.ptr, channel_parameters == null ? 0 : channel_parameters.ptr & ~1);
492 this.ptrs_to.add(channel_parameters);
496 * Frees any resources associated with this object given its this_arg pointer.
497 * Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
499 public ChannelPublicKeys get_pubkeys() {
500 long ret = bindings.BaseSign_get_pubkeys(this.ptr);
501 if (ret >= 0 && ret <= 4096) { return null; }
502 ChannelPublicKeys ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new ChannelPublicKeys(null, ret); }
503 ret_hu_conv.ptrs_to.add(this);