_ 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 import javax.annotation.Nullable;
   8
   9 /**
  10  * A trait to sign lightning channel transactions as described in BOLT 3.
  11  *
  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.
  18  *
  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.
  23  *
  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.
  27  */
  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;
  37         }
  38         @Override @SuppressWarnings("deprecation")
  39         protected void finalize() throws Throwable {
  40                 if (ptr != 0) { bindings.BaseSign_free(ptr); } super.finalize();
  41         }
  42
  43         public static interface BaseSignInterface {
  44                 /**
  45                  * Gets the per-commitment point for a specific commitment number
  46                  *
  47                  * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
  48                  */
  49                 byte[] get_per_commitment_point(long idx);
  50                 /**
  51                  * Gets the commitment secret for a specific commitment number as part of the revocation process
  52                  *
  53                  * An external signer implementation should error here if the commitment was already signed
  54                  * and should refuse to sign it in the future.
  55                  *
  56                  * May be called more than once for the same index.
  57                  *
  58                  * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
  59                  */
  60                 byte[] release_commitment_secret(long idx);
  61                 /**
  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.
  65                  */
  66                 byte[] channel_keys_id();
  67                 /**
  68                  * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
  69                  *
  70                  * Note that if signing fails or is rejected, the channel will be force-closed.
  71                  */
  72                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_counterparty_commitment(CommitmentTransaction commitment_tx);
  73                 /**
  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
  79                  * the latest.
  80                  * This may be called multiple times for the same transaction.
  81                  *
  82                  * An external signer implementation should check that the commitment has not been revoked.
  83                  *
  84                  * May return Err if key derivation fails.  Callers, such as ChannelMonitor, will panic in such a case.
  85                  */
  86                 Result_C2Tuple_SignatureCVec_SignatureZZNoneZ sign_holder_commitment_and_htlcs(HolderCommitmentTransaction commitment_tx);
  87                 /**
  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.
  90                  *
  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.
  95                  *
  96                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
  97                  *
  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
 101                  * so).
 102                  */
 103                 Result_SignatureNoneZ sign_justice_revoked_output(byte[] justice_tx, long input, long amount, byte[] per_commitment_key);
 104                 /**
 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.
 107                  *
 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.
 112                  *
 113                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 114                  *
 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
 118                  * so).
 119                  *
 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).
 122                  */
 123                 Result_SignatureNoneZ sign_justice_revoked_htlc(byte[] justice_tx, long input, long amount, byte[] per_commitment_key, HTLCOutputInCommitment htlc);
 124                 /**
 125                  * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
 126                  * transaction, either offered or received.
 127                  *
 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.
 132                  *
 133                  * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
 134                  * outputs.
 135                  *
 136                  * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 137                  *
 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
 141                  * BIP 143 signature.
 142                  */
 143                 Result_SignatureNoneZ sign_counterparty_htlc_transaction(byte[] htlc_tx, long input, long amount, byte[] per_commitment_point, HTLCOutputInCommitment htlc);
 144                 /**
 145                  * Create a signature for a (proposed) closing transaction.
 146                  *
 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.
 149                  */
 150                 Result_SignatureNoneZ sign_closing_transaction(byte[] closing_tx);
 151                 /**
 152                  * Signs a channel announcement message with our funding key, proving it comes from one
 153                  * of the channel participants.
 154                  *
 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
 157                  * protocol.
 158                  */
 159                 Result_SignatureNoneZ sign_channel_announcement(UnsignedChannelAnnouncement msg);
 160                 /**
 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.
 165                  *
 166                  * channel_parameters.is_populated() MUST be true.
 167                  *
 168                  * We bind holder_selected_contest_delay late here for API convenience.
 169                  *
 170                  * Will be called before any signatures are applied.
 171                  */
 172                 void ready_channel(ChannelTransactionParameters channel_parameters);
 173         }
 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);
 180                                 return ret;
 181                         }
 182                         @Override public byte[] release_commitment_secret(long idx) {
 183                                 byte[] ret = arg.release_commitment_secret(idx);
 184                                 return ret;
 185                         }
 186                         @Override public byte[] channel_keys_id() {
 187                                 byte[] ret = arg.channel_keys_id();
 188                                 return ret;
 189                         }
 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;
 194                                 return result;
 195                         }
 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;
 200                                 return result;
 201                         }
 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;
 205                                 return result;
 206                         }
 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;
 211                                 return result;
 212                         }
 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;
 217                                 return result;
 218                         }
 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;
 222                                 return result;
 223                         }
 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;
 228                                 return result;
 229                         }
 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);
 233                         }
 234                 }, pubkeys);
 235                 return impl_holder.held;
 236         }
 237         /**
 238          * Gets the per-commitment point for a specific commitment number
 239          *
 240          * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
 241          */
 242         public byte[] get_per_commitment_point(long idx) {
 243                 byte[] ret = bindings.BaseSign_get_per_commitment_point(this.ptr, idx);
 244                 return ret;
 245         }
 246
 247         /**
 248          * Gets the commitment secret for a specific commitment number as part of the revocation process
 249          *
 250          * An external signer implementation should error here if the commitment was already signed
 251          * and should refuse to sign it in the future.
 252          *
 253          * May be called more than once for the same index.
 254          *
 255          * Note that the commitment number starts at (1 << 48) - 1 and counts backwards.
 256          */
 257         public byte[] release_commitment_secret(long idx) {
 258                 byte[] ret = bindings.BaseSign_release_commitment_secret(this.ptr, idx);
 259                 return ret;
 260         }
 261
 262         /**
 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.
 266          */
 267         public byte[] channel_keys_id() {
 268                 byte[] ret = bindings.BaseSign_channel_keys_id(this.ptr);
 269                 return ret;
 270         }
 271
 272         /**
 273          * Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
 274          *
 275          * Note that if signing fails or is rejected, the channel will be force-closed.
 276          */
 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);
 282                 return ret_hu_conv;
 283         }
 284
 285         /**
 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
 291          * the latest.
 292          * This may be called multiple times for the same transaction.
 293          *
 294          * An external signer implementation should check that the commitment has not been revoked.
 295          *
 296          * May return Err if key derivation fails.  Callers, such as ChannelMonitor, will panic in such a case.
 297          */
 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);
 303                 return ret_hu_conv;
 304         }
 305
 306         /**
 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.
 309          *
 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.
 314          *
 315          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 316          *
 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
 320          * so).
 321          */
 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);
 326                 return ret_hu_conv;
 327         }
 328
 329         /**
 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.
 332          *
 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.
 337          *
 338          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 339          *
 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
 343          * so).
 344          *
 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).
 347          */
 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);
 353                 return ret_hu_conv;
 354         }
 355
 356         /**
 357          * Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
 358          * transaction, either offered or received.
 359          *
 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.
 364          *
 365          * Witness_script is either a offered or received script as defined in BOLT3 for HTLC
 366          * outputs.
 367          *
 368          * Amount is value of the output spent by this input, committed to in the BIP 143 signature.
 369          *
 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
 373          * BIP 143 signature.
 374          */
 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);
 380                 return ret_hu_conv;
 381         }
 382
 383         /**
 384          * Create a signature for a (proposed) closing transaction.
 385          *
 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.
 388          */
 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);
 393                 return ret_hu_conv;
 394         }
 395
 396         /**
 397          * Signs a channel announcement message with our funding key, proving it comes from one
 398          * of the channel participants.
 399          *
 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
 402          * protocol.
 403          */
 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);
 409                 return ret_hu_conv;
 410         }
 411
 412         /**
 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.
 417          *
 418          * channel_parameters.is_populated() MUST be true.
 419          *
 420          * We bind holder_selected_contest_delay late here for API convenience.
 421          *
 422          * Will be called before any signatures are applied.
 423          */
 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);
 427         }
 428
 429         /**
 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.
 432          */
 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);
 438                 return ret_hu_conv;
 439         }
 440
 441 }