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.ptr & ~1));
34 this.ptrs_to.add(arg);
35 this.ptrs_to.add(pubkeys);
36 this.bindings_instance = arg;
38 @Override @SuppressWarnings("deprecation")
39 protected void finalize() throws Throwable {
40 if (ptr != 0) { bindings.BaseSign_free(ptr); } super.finalize();
43 public static interface BaseSignInterface {
45 * Gets the per-commitment point for a specific commitment number
47 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
49 byte[] get_per_commitment_point(long idx);
51 * Gets the commitment secret for a specific commitment number as part of the revocation process
53 * An external signer implementation should error here if the commitment was already signed
54 * and should refuse to sign it in the future.
56 * May be called more than once for the same index.
58 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
60 byte[] release_commitment_secret(long idx);
62 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
63 * some SpendableOutputDescriptor types. This should be sufficient to identify this
64 * Sign object uniquely and lookup or re-derive its keys.
66 byte[] channel_keys_id();
68 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
70 * Note that if signing fails or is rejected, the channel will be force-closed.
72 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx);
74 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
75 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
76 * latest commitment_tx when we initiate a force-close.
77 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
78 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
80 * This may be called multiple times for the same transaction.
82 * An external signer implementation should check that the commitment has not been revoked.
84 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
86 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx);
88 * Create a signature for the given input in a transaction spending an HTLC transaction output
89 * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
91 * A justice transaction may claim multiple outputs at the same time if timelocks are
92 * similar, but only a signature for the input at index `input` should be signed for here.
93 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
94 * to an upcoming timelock expiration.
96 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
98 * per_commitment_key is revocation secret which was provided by our counterparty when they
99 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
100 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
103 Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key);
105 * Create a signature for the given input in a transaction spending a commitment transaction
106 * HTLC output when our counterparty broadcasts an old state.
108 * A justice transaction may claim multiple outputs at the same time if timelocks are
109 * similar, but only a signature for the input at index `input` should be signed for here.
110 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
111 * to an upcoming timelock expiration.
113 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
115 * per_commitment_key is revocation secret which was provided by our counterparty when they
116 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
117 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
120 * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
121 * (which is committed to in the BIP 143 signatures).
123 Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc);
125 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
126 * transaction, either offered or received.
128 * Such a transaction may claim multiples offered outputs at same time if we know the
129 * preimage for each when we create it, but only the input at index `input` should be
130 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
131 * needed with regards to an upcoming timelock expiration.
133 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
136 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
138 * Per_commitment_point is the dynamic point corresponding to the channel state
139 * detected onchain. It has been generated by our counterparty and is used to derive
140 * channel state keys, which are then included in the witness script and committed to in the
143 Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc);
145 * Create a signature for a (proposed) closing transaction.
147 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
148 * chosen to forgo their output as dust.
150 Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx);
152 * Signs a channel announcement message with our funding key, proving it comes from one
153 * of the channel participants.
155 * Note that if this fails or is rejected, the channel will not be publicly announced and
156 * our counterparty may (though likely will not) close the channel on us for violating the
159 Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg);
161 * Set the counterparty static channel data, including basepoints,
162 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
163 * This is done as soon as the funding outpoint is known. Since these are static channel data,
164 * they MUST NOT be allowed to change to different values once set.
166 * channel_parameters.is_populated() MUST be true.
168 * We bind holder_selected_contest_delay late here for API convenience.
170 * Will be called before any signatures are applied.
172 void ready_channel(ChannelTransactionParameters channel_parameters);
174 private static class LDKBaseSignHolder { BaseSign held; }
175 public static BaseSign new_impl(BaseSignInterface arg, ChannelPublicKeys pubkeys) {
176 final LDKBaseSignHolder impl_holder = new LDKBaseSignHolder();
177 impl_holder.held = new BaseSign(new bindings.LDKBaseSign() {
178 @Override public byte[] get_per_commitment_point(long idx) {
179 byte[] ret = arg.get_per_commitment_point(idx);
182 @Override public byte[] release_commitment_secret(long idx) {
183 byte[] ret = arg.release_commitment_secret(idx);
186 @Override public byte[] channel_keys_id() {
187 byte[] ret = arg.channel_keys_id();
190 @Override public long sign_counterparty_commitment(long commitment_tx) {
191 CommitmentTransaction commitment_tx_hu_conv = new CommitmentTransaction(null, commitment_tx);
192 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_counterparty_commitment(commitment_tx_hu_conv);
193 long result = ret != null ? ret.ptr : 0;
196 @Override public long sign_holder_commitment_and_htlcs(long commitment_tx) {
197 HolderCommitmentTransaction commitment_tx_hu_conv = new HolderCommitmentTransaction(null, commitment_tx);
198 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_holder_commitment_and_htlcs(commitment_tx_hu_conv);
199 long result = ret != null ? ret.ptr : 0;
202 @Override public long sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
203 Result_SignatureNoneZ ret = arg.sign_justice_revoked_output(justice_tx, input, amount, per_commitment_key);
204 long result = ret != null ? ret.ptr : 0;
207 @Override public long sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, long htlc) {
208 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
209 Result_SignatureNoneZ ret = arg.sign_justice_revoked_htlc(justice_tx, input, amount, per_commitment_key, htlc_hu_conv);
210 long result = ret != null ? ret.ptr : 0;
213 @Override public long sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, long htlc) {
214 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
215 Result_SignatureNoneZ ret = arg.sign_counterparty_htlc_transaction(htlc_tx, input, amount, per_commitment_point, htlc_hu_conv);
216 long result = ret != null ? ret.ptr : 0;
219 @Override public long sign_closing_transaction(byte[] closing_tx) {
220 Result_SignatureNoneZ ret = arg.sign_closing_transaction(closing_tx);
221 long result = ret != null ? ret.ptr : 0;
224 @Override public long sign_channel_announcement(long msg) {
225 UnsignedChannelAnnouncement msg_hu_conv = new UnsignedChannelAnnouncement(null, msg);
226 Result_SignatureNoneZ ret = arg.sign_channel_announcement(msg_hu_conv);
227 long result = ret != null ? ret.ptr : 0;
230 @Override public void ready_channel(long channel_parameters) {
231 ChannelTransactionParameters channel_parameters_hu_conv = new ChannelTransactionParameters(null, channel_parameters);
232 arg.ready_channel(channel_parameters_hu_conv);
235 return impl_holder.held;
238 * Gets the per-commitment point for a specific commitment number
240 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
242 public byte[] get_per_commitment_point(long idx) {
243 byte[] ret = bindings.BaseSign_get_per_commitment_point(this.ptr, idx);
248 * Gets the commitment secret for a specific commitment number as part of the revocation process
250 * An external signer implementation should error here if the commitment was already signed
251 * and should refuse to sign it in the future.
253 * May be called more than once for the same index.
255 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
257 public byte[] release_commitment_secret(long idx) {
258 byte[] ret = bindings.BaseSign_release_commitment_secret(this.ptr, idx);
263 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
264 * some SpendableOutputDescriptor types. This should be sufficient to identify this
265 * Sign object uniquely and lookup or re-derive its keys.
267 public byte[] channel_keys_id() {
268 byte[] ret = bindings.BaseSign_channel_keys_id(this.ptr);
273 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
275 * Note that if signing fails or is rejected, the channel will be force-closed.
277 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx) {
278 long ret = bindings.BaseSign_sign_counterparty_commitment(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
279 if (ret < 1024) { return null; }
280 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
281 this.ptrs_to.add(commitment_tx);
286 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
287 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
288 * latest commitment_tx when we initiate a force-close.
289 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
290 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
292 * This may be called multiple times for the same transaction.
294 * An external signer implementation should check that the commitment has not been revoked.
296 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
298 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx) {
299 long ret = bindings.BaseSign_sign_holder_commitment_and_htlcs(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
300 if (ret < 1024) { return null; }
301 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
302 this.ptrs_to.add(commitment_tx);
307 * Create a signature for the given input in a transaction spending an HTLC transaction output
308 * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
310 * A justice transaction may claim multiple outputs at the same time if timelocks are
311 * similar, but only a signature for the input at index `input` should be signed for here.
312 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
313 * to an upcoming timelock expiration.
315 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
317 * per_commitment_key is revocation secret which was provided by our counterparty when they
318 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
319 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
322 public Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
323 long ret = bindings.BaseSign_sign_justice_revoked_output(this.ptr, justice_tx, input, amount, per_commitment_key);
324 if (ret < 1024) { return null; }
325 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
330 * Create a signature for the given input in a transaction spending a commitment transaction
331 * HTLC output when our counterparty broadcasts an old state.
333 * A justice transaction may claim multiple outputs at the same time if timelocks are
334 * similar, but only a signature for the input at index `input` should be signed for here.
335 * It may be called multiple times for same output(s) if a fee-bump is needed with regards
336 * to an upcoming timelock expiration.
338 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
340 * per_commitment_key is revocation secret which was provided by our counterparty when they
341 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
342 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
345 * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
346 * (which is committed to in the BIP 143 signatures).
348 public Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc) {
349 long ret = bindings.BaseSign_sign_justice_revoked_htlc(this.ptr, justice_tx, input, amount, per_commitment_key, htlc == null ? 0 : htlc.ptr & ~1);
350 if (ret < 1024) { return null; }
351 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
352 this.ptrs_to.add(htlc);
357 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
358 * transaction, either offered or received.
360 * Such a transaction may claim multiples offered outputs at same time if we know the
361 * preimage for each when we create it, but only the input at index `input` should be
362 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
363 * needed with regards to an upcoming timelock expiration.
365 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
368 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
370 * Per_commitment_point is the dynamic point corresponding to the channel state
371 * detected onchain. It has been generated by our counterparty and is used to derive
372 * channel state keys, which are then included in the witness script and committed to in the
375 public Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc) {
376 long ret = bindings.BaseSign_sign_counterparty_htlc_transaction(this.ptr, htlc_tx, input, amount, per_commitment_point, htlc == null ? 0 : htlc.ptr & ~1);
377 if (ret < 1024) { return null; }
378 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
379 this.ptrs_to.add(htlc);
384 * Create a signature for a (proposed) closing transaction.
386 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
387 * chosen to forgo their output as dust.
389 public Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx) {
390 long ret = bindings.BaseSign_sign_closing_transaction(this.ptr, closing_tx);
391 if (ret < 1024) { return null; }
392 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
397 * Signs a channel announcement message with our funding key, proving it comes from one
398 * of the channel participants.
400 * Note that if this fails or is rejected, the channel will not be publicly announced and
401 * our counterparty may (though likely will not) close the channel on us for violating the
404 public Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg) {
405 long ret = bindings.BaseSign_sign_channel_announcement(this.ptr, msg == null ? 0 : msg.ptr & ~1);
406 if (ret < 1024) { return null; }
407 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
408 this.ptrs_to.add(msg);
413 * Set the counterparty static channel data, including basepoints,
414 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
415 * This is done as soon as the funding outpoint is known. Since these are static channel data,
416 * they MUST NOT be allowed to change to different values once set.
418 * channel_parameters.is_populated() MUST be true.
420 * We bind holder_selected_contest_delay late here for API convenience.
422 * Will be called before any signatures are applied.
424 public void ready_channel(ChannelTransactionParameters channel_parameters) {
425 bindings.BaseSign_ready_channel(this.ptr, channel_parameters == null ? 0 : channel_parameters.ptr & ~1);
426 this.ptrs_to.add(channel_parameters);
430 * Frees any resources associated with this object given its this_arg pointer.
431 * Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
433 public ChannelPublicKeys get_pubkeys() {
434 long ret = bindings.BaseSign_get_pubkeys(this.ptr);
435 if (ret < 1024) { return null; }
436 ChannelPublicKeys ret_hu_conv = new ChannelPublicKeys(null, ret);
437 ret_hu_conv.ptrs_to.add(this);