1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
9 * A trait to sign lightning channel transactions as described in BOLT 3.
11 * Signing services could be implemented on a hardware wallet. In this case,
12 * the current Sign would be a front-end on top of a communication
13 * channel connected to your secure device and lightning key material wouldn't
14 * reside on a hot server. Nevertheless, a this deployment would still need
15 * to trust the ChannelManager to avoid loss of funds as this latest component
16 * could ask to sign commitment transaction with HTLCs paying to attacker pubkeys.
18 * A more secure iteration would be to use hashlock (or payment points) to pair
19 * invoice/incoming HTLCs with outgoing HTLCs to implement a no-trust-ChannelManager
20 * at the price of more state and computation on the hardware wallet side. In the future,
21 * we are looking forward to design such interface.
23 * In any case, ChannelMonitor or fallback watchtowers are always going to be trusted
24 * to act, as liveness and breach reply correctness are always going to be hard requirements
25 * of LN security model, orthogonal of key management issues.
27 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
28 public class BaseSign extends CommonBase {
29 final bindings.LDKBaseSign bindings_instance;
30 BaseSign(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
31 private BaseSign(bindings.LDKBaseSign arg, ChannelPublicKeys pubkeys) {
32 super(bindings.LDKBaseSign_new(arg, pubkeys == null ? 0 : pubkeys.ptr & ~1));
33 this.ptrs_to.add(arg);
34 this.ptrs_to.add(pubkeys);
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 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
62 * some SpendableOutputDescriptor types. This should be sufficient to identify this
63 * Sign object uniquely and lookup or re-derive its keys.
65 byte[] channel_keys_id();
67 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
69 * Note that if signing fails or is rejected, the channel will be force-closed.
71 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx);
73 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
74 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
75 * latest commitment_tx when we initiate a force-close.
76 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
77 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
79 * This may be called multiple times for the same transaction.
81 * An external signer implementation should check that the commitment has not been revoked.
83 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
85 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx);
87 * Create a signature for the given input in a transaction spending an HTLC or commitment
88 * transaction output when our counterparty broadcasts an old state.
90 * A justice transaction may claim multiples outputs at the same time if timelocks are
91 * similar, but only a signature for the input at index `input` should be signed for here.
92 * It may be called multiples time for same output(s) if a fee-bump is needed with regards
93 * to an upcoming timelock expiration.
95 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
97 * per_commitment_key is revocation secret which was provided by our counterparty when they
98 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
99 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
102 * htlc holds HTLC elements (hash, timelock) if the output being spent is a HTLC output, thus
103 * changing the format of the witness script (which is committed to in the BIP 143
106 Result_SignatureNoneZ sign_justice_transaction(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc);
108 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
109 * transaction, either offered or received.
111 * Such a transaction may claim multiples offered outputs at same time if we know the
112 * preimage for each when we create it, but only the input at index `input` should be
113 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
114 * needed with regards to an upcoming timelock expiration.
116 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
119 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
121 * Per_commitment_point is the dynamic point corresponding to the channel state
122 * detected onchain. It has been generated by our counterparty and is used to derive
123 * channel state keys, which are then included in the witness script and committed to in the
126 Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc);
128 * Create a signature for a (proposed) closing transaction.
130 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
131 * chosen to forgo their output as dust.
133 Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx);
135 * Signs a channel announcement message with our funding key, proving it comes from one
136 * of the channel participants.
138 * Note that if this fails or is rejected, the channel will not be publicly announced and
139 * our counterparty may (though likely will not) close the channel on us for violating the
142 Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg);
144 * Set the counterparty static channel data, including basepoints,
145 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
146 * This is done as soon as the funding outpoint is known. Since these are static channel data,
147 * they MUST NOT be allowed to change to different values once set.
149 * channel_parameters.is_populated() MUST be true.
151 * We bind holder_selected_contest_delay late here for API convenience.
153 * Will be called before any signatures are applied.
155 void ready_channel(ChannelTransactionParameters channel_parameters);
157 private static class LDKBaseSignHolder { BaseSign held; }
158 public static BaseSign new_impl(BaseSignInterface arg, ChannelPublicKeys pubkeys) {
159 final LDKBaseSignHolder impl_holder = new LDKBaseSignHolder();
160 impl_holder.held = new BaseSign(new bindings.LDKBaseSign() {
161 @Override public byte[] get_per_commitment_point(long idx) {
162 byte[] ret = arg.get_per_commitment_point(idx);
165 @Override public byte[] release_commitment_secret(long idx) {
166 byte[] ret = arg.release_commitment_secret(idx);
169 @Override public byte[] channel_keys_id() {
170 byte[] ret = arg.channel_keys_id();
173 @Override public long sign_counterparty_commitment(long commitment_tx) {
174 CommitmentTransaction commitment_tx_hu_conv = new CommitmentTransaction(null, commitment_tx);
175 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_counterparty_commitment(commitment_tx_hu_conv);
176 long result = ret != null ? ret.ptr : 0;
179 @Override public long sign_holder_commitment_and_htlcs(long commitment_tx) {
180 HolderCommitmentTransaction commitment_tx_hu_conv = new HolderCommitmentTransaction(null, commitment_tx);
181 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_holder_commitment_and_htlcs(commitment_tx_hu_conv);
182 long result = ret != null ? ret.ptr : 0;
185 @Override public long sign_justice_transaction(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, long htlc) {
186 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
187 Result_SignatureNoneZ ret = arg.sign_justice_transaction(justice_tx, input, amount, per_commitment_key, htlc_hu_conv);
188 long result = ret != null ? ret.ptr : 0;
191 @Override public long sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, long htlc) {
192 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
193 Result_SignatureNoneZ ret = arg.sign_counterparty_htlc_transaction(htlc_tx, input, amount, per_commitment_point, htlc_hu_conv);
194 long result = ret != null ? ret.ptr : 0;
197 @Override public long sign_closing_transaction(byte[] closing_tx) {
198 Result_SignatureNoneZ ret = arg.sign_closing_transaction(closing_tx);
199 long result = ret != null ? ret.ptr : 0;
202 @Override public long sign_channel_announcement(long msg) {
203 UnsignedChannelAnnouncement msg_hu_conv = new UnsignedChannelAnnouncement(null, msg);
204 Result_SignatureNoneZ ret = arg.sign_channel_announcement(msg_hu_conv);
205 long result = ret != null ? ret.ptr : 0;
208 @Override public void ready_channel(long channel_parameters) {
209 ChannelTransactionParameters channel_parameters_hu_conv = new ChannelTransactionParameters(null, channel_parameters);
210 arg.ready_channel(channel_parameters_hu_conv);
213 return impl_holder.held;
216 * Gets the per-commitment point for a specific commitment number
218 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
220 public byte[] get_per_commitment_point(long idx) {
221 byte[] ret = bindings.BaseSign_get_per_commitment_point(this.ptr, idx);
226 * Gets the commitment secret for a specific commitment number as part of the revocation process
228 * An external signer implementation should error here if the commitment was already signed
229 * and should refuse to sign it in the future.
231 * May be called more than once for the same index.
233 * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
235 public byte[] release_commitment_secret(long idx) {
236 byte[] ret = bindings.BaseSign_release_commitment_secret(this.ptr, idx);
241 * Gets an arbitrary identifier describing the set of keys which are provided back to you in
242 * some SpendableOutputDescriptor types. This should be sufficient to identify this
243 * Sign object uniquely and lookup or re-derive its keys.
245 public byte[] channel_keys_id() {
246 byte[] ret = bindings.BaseSign_channel_keys_id(this.ptr);
251 * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
253 * Note that if signing fails or is rejected, the channel will be force-closed.
255 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx) {
256 long ret = bindings.BaseSign_sign_counterparty_commitment(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
257 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
258 this.ptrs_to.add(commitment_tx);
263 * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
264 * This will only ever be called with a non-revoked commitment_tx. This will be called with the
265 * latest commitment_tx when we initiate a force-close.
266 * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
267 * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
269 * This may be called multiple times for the same transaction.
271 * An external signer implementation should check that the commitment has not been revoked.
273 * May return Err if key derivation fails. Callers, such as ChannelMonitor, will panic in such a case.
275 public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx) {
276 long ret = bindings.BaseSign_sign_holder_commitment_and_htlcs(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
277 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
278 this.ptrs_to.add(commitment_tx);
283 * Create a signature for the given input in a transaction spending an HTLC or commitment
284 * transaction output when our counterparty broadcasts an old state.
286 * A justice transaction may claim multiples outputs at the same time if timelocks are
287 * similar, but only a signature for the input at index `input` should be signed for here.
288 * It may be called multiples time for same output(s) if a fee-bump is needed with regards
289 * to an upcoming timelock expiration.
291 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
293 * per_commitment_key is revocation secret which was provided by our counterparty when they
294 * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
295 * not allow the spending of any funds by itself (you need our holder revocation_secret to do
298 * htlc holds HTLC elements (hash, timelock) if the output being spent is a HTLC output, thus
299 * changing the format of the witness script (which is committed to in the BIP 143
302 public Result_SignatureNoneZ sign_justice_transaction(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc) {
303 long ret = bindings.BaseSign_sign_justice_transaction(this.ptr, justice_tx, input, amount, per_commitment_key, htlc == null ? 0 : htlc.ptr & ~1);
304 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
305 this.ptrs_to.add(htlc);
310 * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
311 * transaction, either offered or received.
313 * Such a transaction may claim multiples offered outputs at same time if we know the
314 * preimage for each when we create it, but only the input at index `input` should be
315 * signed for here. It may be called multiple times for same output(s) if a fee-bump is
316 * needed with regards to an upcoming timelock expiration.
318 * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
321 * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
323 * Per_commitment_point is the dynamic point corresponding to the channel state
324 * detected onchain. It has been generated by our counterparty and is used to derive
325 * channel state keys, which are then included in the witness script and committed to in the
328 public Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc) {
329 long ret = bindings.BaseSign_sign_counterparty_htlc_transaction(this.ptr, htlc_tx, input, amount, per_commitment_point, htlc == null ? 0 : htlc.ptr & ~1);
330 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
331 this.ptrs_to.add(htlc);
336 * Create a signature for a (proposed) closing transaction.
338 * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
339 * chosen to forgo their output as dust.
341 public Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx) {
342 long ret = bindings.BaseSign_sign_closing_transaction(this.ptr, closing_tx);
343 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
348 * Signs a channel announcement message with our funding key, proving it comes from one
349 * of the channel participants.
351 * Note that if this fails or is rejected, the channel will not be publicly announced and
352 * our counterparty may (though likely will not) close the channel on us for violating the
355 public Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg) {
356 long ret = bindings.BaseSign_sign_channel_announcement(this.ptr, msg == null ? 0 : msg.ptr & ~1);
357 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
358 this.ptrs_to.add(msg);
363 * Set the counterparty static channel data, including basepoints,
364 * counterparty_selected/holder_selected_contest_delay and funding outpoint.
365 * This is done as soon as the funding outpoint is known. Since these are static channel data,
366 * they MUST NOT be allowed to change to different values once set.
368 * channel_parameters.is_populated() MUST be true.
370 * We bind holder_selected_contest_delay late here for API convenience.
372 * Will be called before any signatures are applied.
374 public void ready_channel(ChannelTransactionParameters channel_parameters) {
375 bindings.BaseSign_ready_channel(this.ptr, channel_parameters == null ? 0 : channel_parameters.ptr & ~1);
376 this.ptrs_to.add(channel_parameters);
380 * Frees any resources associated with this object given its this_arg pointer.
381 * Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
383 public ChannelPublicKeys get_pubkeys() {
384 long ret = bindings.BaseSign_get_pubkeys(this.ptr);
385 ChannelPublicKeys ret_hu_conv = new ChannelPublicKeys(null, ret);
386 ret_hu_conv.ptrs_to.add(this);