_ Git - ldk-java/blob - src/main/java/org/ldk/structs/BaseSign.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7
   8 /**
   9  * A trait to sign lightning channel transactions as described in BOLT 3.
  10  *
  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.
  17  *
  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.
  22  *
  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.
  26  */
  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;
  36         }
  37         @Override @SuppressWarnings("deprecation")
  38         protected void finalize() throws Throwable {
  39                 if (ptr != 0) { bindings.BaseSign_free(ptr); } super.finalize();
  40         }
  41
  42         public static interface BaseSignInterface {
  43                 /**
  44                  * Gets the per-commitment point for a specific commitment number
  45                  *
  46                  * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
  47                  */
  48                 byte[] get_per_commitment_point(long idx);
  49                 /**
  50                  * Gets the commitment secret for a specific commitment number as part of the revocation process
  51                  *
  52                  * An external signer implementation should error here if the commitment was already signed
  53                  * and should refuse to sign it in the future.
  54                  *
  55                  * May be called more than once for the same index.
  56                  *
  57                  * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
  58                  */
  59                 byte[] release_commitment_secret(long idx);
  60                 /**
  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.
  64                  */
  65                 byte[] channel_keys_id();
  66                 /**
  67                  * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
  68                  *
  69                  * Note that if signing fails or is rejected, the channel will be force-closed.
  70                  */
  71                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx);
  72                 /**
  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
  78                  * the latest.
  79                  * This may be called multiple times for the same transaction.
  80                  *
  81                  * An external signer implementation should check that the commitment has not been revoked.
  82                  *
  83                  * May return Err if key derivation fails.  Callers, such as ChannelMonitor, will panic in such a case.
  84                  */
  85                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx);
  86                 /**
  87                  * Create a signature for the given input in a transaction spending an HTLC transaction output
  88                  * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
  89                  *
  90                  * A justice transaction may claim multiple 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 multiple times for same output(s) if a fee-bump is needed with regards
  93                  * to an upcoming timelock expiration.
  94                  *
  95                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
  96                  *
  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
 100                  * so).
 101                  */
 102                 Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key);
 103                 /**
 104                  * Create a signature for the given input in a transaction spending a commitment transaction
 105                  * HTLC output when our counterparty broadcasts an old state.
 106                  *
 107                  * A justice transaction may claim multiple outputs at the same time if timelocks are
 108                  * similar, but only a signature for the input at index `input` should be signed for here.
 109                  * It may be called multiple times for same output(s) if a fee-bump is needed with regards
 110                  * to an upcoming timelock expiration.
 111                  *
 112                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 113                  *
 114                  * per_commitment_key is revocation secret which was provided by our counterparty when they
 115                  * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
 116                  * not allow the spending of any funds by itself (you need our holder revocation_secret to do
 117                  * so).
 118                  *
 119                  * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
 120                  * (which is committed to in the BIP 143 signatures).
 121                  */
 122                 Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc);
 123                 /**
 124                  * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
 125                  * transaction, either offered or received.
 126                  *
 127                  * Such a transaction may claim multiples offered outputs at same time if we know the
 128                  * preimage for each when we create it, but only the input at index `input` should be
 129                  * signed for here. It may be called multiple times for same output(s) if a fee-bump is
 130                  * needed with regards to an upcoming timelock expiration.
 131                  *
 132                  * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
 133                  * outputs.
 134                  *
 135                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 136                  *
 137                  * Per_commitment_point is the dynamic point corresponding to the channel state
 138                  * detected onchain. It has been generated by our counterparty and is used to derive
 139                  * channel state keys, which are then included in the witness script and committed to in the
 140                  * BIP 143 signature.
 141                  */
 142                 Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc);
 143                 /**
 144                  * Create a signature for a (proposed) closing transaction.
 145                  *
 146                  * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
 147                  * chosen to forgo their output as dust.
 148                  */
 149                 Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx);
 150                 /**
 151                  * Signs a channel announcement message with our funding key, proving it comes from one
 152                  * of the channel participants.
 153                  *
 154                  * Note that if this fails or is rejected, the channel will not be publicly announced and
 155                  * our counterparty may (though likely will not) close the channel on us for violating the
 156                  * protocol.
 157                  */
 158                 Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg);
 159                 /**
 160                  * Set the counterparty static channel data, including basepoints,
 161                  * counterparty_selected/holder_selected_contest_delay and funding outpoint.
 162                  * This is done as soon as the funding outpoint is known.  Since these are static channel data,
 163                  * they MUST NOT be allowed to change to different values once set.
 164                  *
 165                  * channel_parameters.is_populated() MUST be true.
 166                  *
 167                  * We bind holder_selected_contest_delay late here for API convenience.
 168                  *
 169                  * Will be called before any signatures are applied.
 170                  */
 171                 void ready_channel(ChannelTransactionParameters channel_parameters);
 172         }
 173         private static class LDKBaseSignHolder { BaseSign held; }
 174         public static BaseSign new_impl(BaseSignInterface arg, ChannelPublicKeys pubkeys) {
 175                 final LDKBaseSignHolder impl_holder = new LDKBaseSignHolder();
 176                 impl_holder.held = new BaseSign(new bindings.LDKBaseSign() {
 177                         @Override public byte[] get_per_commitment_point(long idx) {
 178                                 byte[] ret = arg.get_per_commitment_point(idx);
 179                                 return ret;
 180                         }
 181                         @Override public byte[] release_commitment_secret(long idx) {
 182                                 byte[] ret = arg.release_commitment_secret(idx);
 183                                 return ret;
 184                         }
 185                         @Override public byte[] channel_keys_id() {
 186                                 byte[] ret = arg.channel_keys_id();
 187                                 return ret;
 188                         }
 189                         @Override public long sign_counterparty_commitment(long commitment_tx) {
 190                                 CommitmentTransaction commitment_tx_hu_conv = new CommitmentTransaction(null, commitment_tx);
 191                                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_counterparty_commitment(commitment_tx_hu_conv);
 192                                 long result = ret != null ? ret.ptr : 0;
 193                                 return result;
 194                         }
 195                         @Override public long sign_holder_commitment_and_htlcs(long commitment_tx) {
 196                                 HolderCommitmentTransaction commitment_tx_hu_conv = new HolderCommitmentTransaction(null, commitment_tx);
 197                                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret = arg.sign_holder_commitment_and_htlcs(commitment_tx_hu_conv);
 198                                 long result = ret != null ? ret.ptr : 0;
 199                                 return result;
 200                         }
 201                         @Override public long sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
 202                                 Result_SignatureNoneZ ret = arg.sign_justice_revoked_output(justice_tx, input, amount, per_commitment_key);
 203                                 long result = ret != null ? ret.ptr : 0;
 204                                 return result;
 205                         }
 206                         @Override public long sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, long htlc) {
 207                                 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
 208                                 Result_SignatureNoneZ ret = arg.sign_justice_revoked_htlc(justice_tx, input, amount, per_commitment_key, htlc_hu_conv);
 209                                 long result = ret != null ? ret.ptr : 0;
 210                                 return result;
 211                         }
 212                         @Override public long sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, long htlc) {
 213                                 HTLCOutputInCommitment htlc_hu_conv = new HTLCOutputInCommitment(null, htlc);
 214                                 Result_SignatureNoneZ ret = arg.sign_counterparty_htlc_transaction(htlc_tx, input, amount, per_commitment_point, htlc_hu_conv);
 215                                 long result = ret != null ? ret.ptr : 0;
 216                                 return result;
 217                         }
 218                         @Override public long sign_closing_transaction(byte[] closing_tx) {
 219                                 Result_SignatureNoneZ ret = arg.sign_closing_transaction(closing_tx);
 220                                 long result = ret != null ? ret.ptr : 0;
 221                                 return result;
 222                         }
 223                         @Override public long sign_channel_announcement(long msg) {
 224                                 UnsignedChannelAnnouncement msg_hu_conv = new UnsignedChannelAnnouncement(null, msg);
 225                                 Result_SignatureNoneZ ret = arg.sign_channel_announcement(msg_hu_conv);
 226                                 long result = ret != null ? ret.ptr : 0;
 227                                 return result;
 228                         }
 229                         @Override public void ready_channel(long channel_parameters) {
 230                                 ChannelTransactionParameters channel_parameters_hu_conv = new ChannelTransactionParameters(null, channel_parameters);
 231                                 arg.ready_channel(channel_parameters_hu_conv);
 232                         }
 233                 }, pubkeys);
 234                 return impl_holder.held;
 235         }
 236         /**
 237          * Gets the per-commitment point for a specific commitment number
 238          *
 239          * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
 240          */
 241         public byte[] get_per_commitment_point(long idx) {
 242                 byte[] ret = bindings.BaseSign_get_per_commitment_point(this.ptr, idx);
 243                 return ret;
 244         }
 245
 246         /**
 247          * Gets the commitment secret for a specific commitment number as part of the revocation process
 248          *
 249          * An external signer implementation should error here if the commitment was already signed
 250          * and should refuse to sign it in the future.
 251          *
 252          * May be called more than once for the same index.
 253          *
 254          * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
 255          */
 256         public byte[] release_commitment_secret(long idx) {
 257                 byte[] ret = bindings.BaseSign_release_commitment_secret(this.ptr, idx);
 258                 return ret;
 259         }
 260
 261         /**
 262          * Gets an arbitrary identifier describing the set of keys which are provided back to you in
 263          * some SpendableOutputDescriptor types. This should be sufficient to identify this
 264          * Sign object uniquely and lookup or re-derive its keys.
 265          */
 266         public byte[] channel_keys_id() {
 267                 byte[] ret = bindings.BaseSign_channel_keys_id(this.ptr);
 268                 return ret;
 269         }
 270
 271         /**
 272          * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
 273          *
 274          * Note that if signing fails or is rejected, the channel will be force-closed.
 275          */
 276         public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx) {
 277                 long ret = bindings.BaseSign_sign_counterparty_commitment(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
 278                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
 279                 this.ptrs_to.add(commitment_tx);
 280                 return ret_hu_conv;
 281         }
 282
 283         /**
 284          * Create a signatures for a holder's commitment transaction and its claiming HTLC transactions.
 285          * This will only ever be called with a non-revoked commitment_tx.  This will be called with the
 286          * latest commitment_tx when we initiate a force-close.
 287          * This will be called with the previous latest, just to get claiming HTLC signatures, if we are
 288          * reacting to a ChannelMonitor replica that decided to broadcast before it had been updated to
 289          * the latest.
 290          * This may be called multiple times for the same transaction.
 291          *
 292          * An external signer implementation should check that the commitment has not been revoked.
 293          *
 294          * May return Err if key derivation fails.  Callers, such as ChannelMonitor, will panic in such a case.
 295          */
 296         public Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx) {
 297                 long ret = bindings.BaseSign_sign_holder_commitment_and_htlcs(this.ptr, commitment_tx == null ? 0 : commitment_tx.ptr & ~1);
 298                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ ret_hu_conv = Result_C2Tuple_SignatureCVec_SignatureZZNoneZ.constr_from_ptr(ret);
 299                 this.ptrs_to.add(commitment_tx);
 300                 return ret_hu_conv;
 301         }
 302
 303         /**
 304          * Create a signature for the given input in a transaction spending an HTLC transaction output
 305          * or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
 306          *
 307          * A justice transaction may claim multiple outputs at the same time if timelocks are
 308          * similar, but only a signature for the input at index `input` should be signed for here.
 309          * It may be called multiple times for same output(s) if a fee-bump is needed with regards
 310          * to an upcoming timelock expiration.
 311          *
 312          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 313          *
 314          * per_commitment_key is revocation secret which was provided by our counterparty when they
 315          * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
 316          * not allow the spending of any funds by itself (you need our holder revocation_secret to do
 317          * so).
 318          */
 319         public Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key) {
 320                 long ret = bindings.BaseSign_sign_justice_revoked_output(this.ptr, justice_tx, input, amount, per_commitment_key);
 321                 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
 322                 return ret_hu_conv;
 323         }
 324
 325         /**
 326          * Create a signature for the given input in a transaction spending a commitment transaction
 327          * HTLC output when our counterparty broadcasts an old state.
 328          *
 329          * A justice transaction may claim multiple outputs at the same time if timelocks are
 330          * similar, but only a signature for the input at index `input` should be signed for here.
 331          * It may be called multiple times for same output(s) if a fee-bump is needed with regards
 332          * to an upcoming timelock expiration.
 333          *
 334          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 335          *
 336          * per_commitment_key is revocation secret which was provided by our counterparty when they
 337          * revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
 338          * not allow the spending of any funds by itself (you need our holder revocation_secret to do
 339          * so).
 340          *
 341          * htlc holds HTLC elements (hash, timelock), thus changing the format of the witness script
 342          * (which is committed to in the BIP 143 signatures).
 343          */
 344         public Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc) {
 345                 long ret = bindings.BaseSign_sign_justice_revoked_htlc(this.ptr, justice_tx, input, amount, per_commitment_key, htlc == null ? 0 : htlc.ptr & ~1);
 346                 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
 347                 this.ptrs_to.add(htlc);
 348                 return ret_hu_conv;
 349         }
 350
 351         /**
 352          * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
 353          * transaction, either offered or received.
 354          *
 355          * Such a transaction may claim multiples offered outputs at same time if we know the
 356          * preimage for each when we create it, but only the input at index `input` should be
 357          * signed for here. It may be called multiple times for same output(s) if a fee-bump is
 358          * needed with regards to an upcoming timelock expiration.
 359          *
 360          * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
 361          * outputs.
 362          *
 363          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 364          *
 365          * Per_commitment_point is the dynamic point corresponding to the channel state
 366          * detected onchain. It has been generated by our counterparty and is used to derive
 367          * channel state keys, which are then included in the witness script and committed to in the
 368          * BIP 143 signature.
 369          */
 370         public Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc) {
 371                 long ret = bindings.BaseSign_sign_counterparty_htlc_transaction(this.ptr, htlc_tx, input, amount, per_commitment_point, htlc == null ? 0 : htlc.ptr & ~1);
 372                 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
 373                 this.ptrs_to.add(htlc);
 374                 return ret_hu_conv;
 375         }
 376
 377         /**
 378          * Create a signature for a (proposed) closing transaction.
 379          *
 380          * Note that, due to rounding, there may be one \"missing\" satoshi, and either party may have
 381          * chosen to forgo their output as dust.
 382          */
 383         public Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx) {
 384                 long ret = bindings.BaseSign_sign_closing_transaction(this.ptr, closing_tx);
 385                 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
 386                 return ret_hu_conv;
 387         }
 388
 389         /**
 390          * Signs a channel announcement message with our funding key, proving it comes from one
 391          * of the channel participants.
 392          *
 393          * Note that if this fails or is rejected, the channel will not be publicly announced and
 394          * our counterparty may (though likely will not) close the channel on us for violating the
 395          * protocol.
 396          */
 397         public Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg) {
 398                 long ret = bindings.BaseSign_sign_channel_announcement(this.ptr, msg == null ? 0 : msg.ptr & ~1);
 399                 Result_SignatureNoneZ ret_hu_conv = Result_SignatureNoneZ.constr_from_ptr(ret);
 400                 this.ptrs_to.add(msg);
 401                 return ret_hu_conv;
 402         }
 403
 404         /**
 405          * Set the counterparty static channel data, including basepoints,
 406          * counterparty_selected/holder_selected_contest_delay and funding outpoint.
 407          * This is done as soon as the funding outpoint is known.  Since these are static channel data,
 408          * they MUST NOT be allowed to change to different values once set.
 409          *
 410          * channel_parameters.is_populated() MUST be true.
 411          *
 412          * We bind holder_selected_contest_delay late here for API convenience.
 413          *
 414          * Will be called before any signatures are applied.
 415          */
 416         public void ready_channel(ChannelTransactionParameters channel_parameters) {
 417                 bindings.BaseSign_ready_channel(this.ptr, channel_parameters == null ? 0 : channel_parameters.ptr & ~1);
 418                 this.ptrs_to.add(channel_parameters);
 419         }
 420
 421         /**
 422          * Frees any resources associated with this object given its this_arg pointer.
 423          * Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
 424          */
 425         public ChannelPublicKeys get_pubkeys() {
 426                 long ret = bindings.BaseSign_get_pubkeys(this.ptr);
 427                 ChannelPublicKeys ret_hu_conv = new ChannelPublicKeys(null, ret);
 428                 ret_hu_conv.ptrs_to.add(this);
 429                 return ret_hu_conv;
 430         }
 431
 432 }