_ Git - ldk-java/blob - src/main/java/org/ldk/structs/VerifiedInvoiceRequest.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 java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10
  11 /**
  12  * An [`InvoiceRequest`] that has been verified by [`InvoiceRequest::verify`] and exposes different
  13  * ways to respond depending on whether the signing keys were derived.
  14  */
  15 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  16 public class VerifiedInvoiceRequest extends CommonBase {
  17         VerifiedInvoiceRequest(Object _dummy, long ptr) { super(ptr); }
  18         @Override @SuppressWarnings("deprecation")
  19         protected void finalize() throws Throwable {
  20                 super.finalize();
  21                 if (ptr != 0) { bindings.VerifiedInvoiceRequest_free(ptr); }
  22         }
  23
  24         /**
  25          * The identifier of the [`Offer`] for which the [`InvoiceRequest`] was made.
  26          */
  27         public OfferId get_offer_id() {
  28                 long ret = bindings.VerifiedInvoiceRequest_get_offer_id(this.ptr);
  29                 Reference.reachabilityFence(this);
  30                 if (ret >= 0 && ret <= 4096) { return null; }
  31                 org.ldk.structs.OfferId ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OfferId(null, ret); }
  32                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  33                 return ret_hu_conv;
  34         }
  35
  36         /**
  37          * The identifier of the [`Offer`] for which the [`InvoiceRequest`] was made.
  38          */
  39         public void set_offer_id(org.ldk.structs.OfferId val) {
  40                 bindings.VerifiedInvoiceRequest_set_offer_id(this.ptr, val.ptr);
  41                 Reference.reachabilityFence(this);
  42                 Reference.reachabilityFence(val);
  43                 if (this != null) { this.ptrs_to.add(val); };
  44         }
  45
  46         /**
  47          * Keys used for signing a [`Bolt12Invoice`] if they can be derived.
  48          *
  49          * If `Some`, must call [`respond_using_derived_keys`] when responding. Otherwise, call
  50          * [`respond_with`].
  51          *
  52          * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
  53          * [`respond_using_derived_keys`]: Self::respond_using_derived_keys
  54          * [`respond_with`]: Self::respond_with
  55          */
  56         public Option_SecretKeyZ get_keys() {
  57                 long ret = bindings.VerifiedInvoiceRequest_get_keys(this.ptr);
  58                 Reference.reachabilityFence(this);
  59                 if (ret >= 0 && ret <= 4096) { return null; }
  60                 org.ldk.structs.Option_SecretKeyZ ret_hu_conv = org.ldk.structs.Option_SecretKeyZ.constr_from_ptr(ret);
  61                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  62                 return ret_hu_conv;
  63         }
  64
  65         /**
  66          * Keys used for signing a [`Bolt12Invoice`] if they can be derived.
  67          *
  68          * If `Some`, must call [`respond_using_derived_keys`] when responding. Otherwise, call
  69          * [`respond_with`].
  70          *
  71          * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
  72          * [`respond_using_derived_keys`]: Self::respond_using_derived_keys
  73          * [`respond_with`]: Self::respond_with
  74          */
  75         public void set_keys(org.ldk.structs.Option_SecretKeyZ val) {
  76                 bindings.VerifiedInvoiceRequest_set_keys(this.ptr, val.ptr);
  77                 Reference.reachabilityFence(this);
  78                 Reference.reachabilityFence(val);
  79                 if (this != null) { this.ptrs_to.add(val); };
  80         }
  81
  82         long clone_ptr() {
  83                 long ret = bindings.VerifiedInvoiceRequest_clone_ptr(this.ptr);
  84                 Reference.reachabilityFence(this);
  85                 return ret;
  86         }
  87
  88         /**
  89          * Creates a copy of the VerifiedInvoiceRequest
  90          */
  91         public VerifiedInvoiceRequest clone() {
  92                 long ret = bindings.VerifiedInvoiceRequest_clone(this.ptr);
  93                 Reference.reachabilityFence(this);
  94                 if (ret >= 0 && ret <= 4096) { return null; }
  95                 org.ldk.structs.VerifiedInvoiceRequest ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.VerifiedInvoiceRequest(null, ret); }
  96                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  97                 return ret_hu_conv;
  98         }
  99
 100         /**
 101          * The chains that may be used when paying a requested invoice (e.g., bitcoin mainnet).
 102          * Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats)
 103          * for the selected chain.
 104          */
 105         public byte[][] chains() {
 106                 byte[][] ret = bindings.VerifiedInvoiceRequest_chains(this.ptr);
 107                 Reference.reachabilityFence(this);
 108                 return ret;
 109         }
 110
 111         /**
 112          * Opaque bytes set by the originator. Useful for authentication and validating fields since it
 113          * is reflected in `invoice_request` messages along with all the other fields from the `offer`.
 114          */
 115         public Option_CVec_u8ZZ metadata() {
 116                 long ret = bindings.VerifiedInvoiceRequest_metadata(this.ptr);
 117                 Reference.reachabilityFence(this);
 118                 if (ret >= 0 && ret <= 4096) { return null; }
 119                 org.ldk.structs.Option_CVec_u8ZZ ret_hu_conv = org.ldk.structs.Option_CVec_u8ZZ.constr_from_ptr(ret);
 120                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 121                 return ret_hu_conv;
 122         }
 123
 124         /**
 125          * The minimum amount required for a successful payment of a single item.
 126          */
 127         public Option_AmountZ amount() {
 128                 long ret = bindings.VerifiedInvoiceRequest_amount(this.ptr);
 129                 Reference.reachabilityFence(this);
 130                 if (ret >= 0 && ret <= 4096) { return null; }
 131                 org.ldk.structs.Option_AmountZ ret_hu_conv = org.ldk.structs.Option_AmountZ.constr_from_ptr(ret);
 132                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 133                 return ret_hu_conv;
 134         }
 135
 136         /**
 137          * A complete description of the purpose of the payment. Intended to be displayed to the user
 138          * but with the caveat that it has not been verified in any way.
 139          *
 140          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 141          */
 142         @Nullable
 143         public PrintableString description() {
 144                 long ret = bindings.VerifiedInvoiceRequest_description(this.ptr);
 145                 Reference.reachabilityFence(this);
 146                 if (ret >= 0 && ret <= 4096) { return null; }
 147                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 148                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 149                 return ret_hu_conv;
 150         }
 151
 152         /**
 153          * Features pertaining to the offer.
 154          */
 155         public OfferFeatures offer_features() {
 156                 long ret = bindings.VerifiedInvoiceRequest_offer_features(this.ptr);
 157                 Reference.reachabilityFence(this);
 158                 if (ret >= 0 && ret <= 4096) { return null; }
 159                 org.ldk.structs.OfferFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OfferFeatures(null, ret); }
 160                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 161                 return ret_hu_conv;
 162         }
 163
 164         /**
 165          * Duration since the Unix epoch when an invoice should no longer be requested.
 166          *
 167          * If `None`, the offer does not expire.
 168          */
 169         public Option_u64Z absolute_expiry() {
 170                 long ret = bindings.VerifiedInvoiceRequest_absolute_expiry(this.ptr);
 171                 Reference.reachabilityFence(this);
 172                 if (ret >= 0 && ret <= 4096) { return null; }
 173                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 174                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 175                 return ret_hu_conv;
 176         }
 177
 178         /**
 179          * The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
 180          * displayed to the user but with the caveat that it has not been verified in any way.
 181          *
 182          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 183          */
 184         @Nullable
 185         public PrintableString issuer() {
 186                 long ret = bindings.VerifiedInvoiceRequest_issuer(this.ptr);
 187                 Reference.reachabilityFence(this);
 188                 if (ret >= 0 && ret <= 4096) { return null; }
 189                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 190                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 191                 return ret_hu_conv;
 192         }
 193
 194         /**
 195          * Paths to the recipient originating from publicly reachable nodes. Blinded paths provide
 196          * recipient privacy by obfuscating its node id.
 197          */
 198         public BlindedPath[] paths() {
 199                 long[] ret = bindings.VerifiedInvoiceRequest_paths(this.ptr);
 200                 Reference.reachabilityFence(this);
 201                 int ret_conv_13_len = ret.length;
 202                 BlindedPath[] ret_conv_13_arr = new BlindedPath[ret_conv_13_len];
 203                 for (int n = 0; n < ret_conv_13_len; n++) {
 204                         long ret_conv_13 = ret[n];
 205                         org.ldk.structs.BlindedPath ret_conv_13_hu_conv = null; if (ret_conv_13 < 0 || ret_conv_13 > 4096) { ret_conv_13_hu_conv = new org.ldk.structs.BlindedPath(null, ret_conv_13); }
 206                         if (ret_conv_13_hu_conv != null) { ret_conv_13_hu_conv.ptrs_to.add(this); };
 207                         ret_conv_13_arr[n] = ret_conv_13_hu_conv;
 208                 }
 209                 return ret_conv_13_arr;
 210         }
 211
 212         /**
 213          * The quantity of items supported.
 214          */
 215         public Quantity supported_quantity() {
 216                 long ret = bindings.VerifiedInvoiceRequest_supported_quantity(this.ptr);
 217                 Reference.reachabilityFence(this);
 218                 if (ret >= 0 && ret <= 4096) { return null; }
 219                 org.ldk.structs.Quantity ret_hu_conv = org.ldk.structs.Quantity.constr_from_ptr(ret);
 220                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 221                 return ret_hu_conv;
 222         }
 223
 224         /**
 225          * The public key used by the recipient to sign invoices.
 226          *
 227          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 228          */
 229         @Nullable
 230         public byte[] signing_pubkey() {
 231                 byte[] ret = bindings.VerifiedInvoiceRequest_signing_pubkey(this.ptr);
 232                 Reference.reachabilityFence(this);
 233                 return ret;
 234         }
 235
 236         /**
 237          * An unpredictable series of bytes, typically containing information about the derivation of
 238          * [`payer_id`].
 239          *
 240          * [`payer_id`]: Self::payer_id
 241          */
 242         public byte[] payer_metadata() {
 243                 byte[] ret = bindings.VerifiedInvoiceRequest_payer_metadata(this.ptr);
 244                 Reference.reachabilityFence(this);
 245                 return ret;
 246         }
 247
 248         /**
 249          * A chain from [`Offer::chains`] that the offer is valid for.
 250          */
 251         public byte[] chain() {
 252                 byte[] ret = bindings.VerifiedInvoiceRequest_chain(this.ptr);
 253                 Reference.reachabilityFence(this);
 254                 return ret;
 255         }
 256
 257         /**
 258          * The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
 259          * must be greater than or equal to [`Offer::amount`], converted if necessary.
 260          *
 261          * [`chain`]: Self::chain
 262          */
 263         public Option_u64Z amount_msats() {
 264                 long ret = bindings.VerifiedInvoiceRequest_amount_msats(this.ptr);
 265                 Reference.reachabilityFence(this);
 266                 if (ret >= 0 && ret <= 4096) { return null; }
 267                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 268                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 269                 return ret_hu_conv;
 270         }
 271
 272         /**
 273          * Features pertaining to requesting an invoice.
 274          */
 275         public InvoiceRequestFeatures invoice_request_features() {
 276                 long ret = bindings.VerifiedInvoiceRequest_invoice_request_features(this.ptr);
 277                 Reference.reachabilityFence(this);
 278                 if (ret >= 0 && ret <= 4096) { return null; }
 279                 org.ldk.structs.InvoiceRequestFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.InvoiceRequestFeatures(null, ret); }
 280                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 281                 return ret_hu_conv;
 282         }
 283
 284         /**
 285          * The quantity of the offer's item conforming to [`Offer::is_valid_quantity`].
 286          */
 287         public Option_u64Z quantity() {
 288                 long ret = bindings.VerifiedInvoiceRequest_quantity(this.ptr);
 289                 Reference.reachabilityFence(this);
 290                 if (ret >= 0 && ret <= 4096) { return null; }
 291                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 292                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 293                 return ret_hu_conv;
 294         }
 295
 296         /**
 297          * A possibly transient pubkey used to sign the invoice request.
 298          */
 299         public byte[] payer_id() {
 300                 byte[] ret = bindings.VerifiedInvoiceRequest_payer_id(this.ptr);
 301                 Reference.reachabilityFence(this);
 302                 return ret;
 303         }
 304
 305         /**
 306          * A payer-provided note which will be seen by the recipient and reflected back in the invoice
 307          * response.
 308          *
 309          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 310          */
 311         @Nullable
 312         public PrintableString payer_note() {
 313                 long ret = bindings.VerifiedInvoiceRequest_payer_note(this.ptr);
 314                 Reference.reachabilityFence(this);
 315                 if (ret >= 0 && ret <= 4096) { return null; }
 316                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 317                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 318                 return ret_hu_conv;
 319         }
 320
 321         /**
 322          * Creates an [`InvoiceBuilder`] for the request with the given required fields and using the
 323          * [`Duration`] since [`std::time::SystemTime::UNIX_EPOCH`] as the creation time.
 324          *
 325          * See [`InvoiceRequest::respond_with_no_std`] for further details where the aforementioned
 326          * creation time is used for the `created_at` parameter.
 327          *
 328          * [`Duration`]: core::time::Duration
 329          */
 330         public Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ respond_with(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash) {
 331                 long ret = bindings.VerifiedInvoiceRequest_respond_with(this.ptr, payment_paths != null ? Arrays.stream(payment_paths).mapToLong(payment_paths_conv_37 -> payment_paths_conv_37.ptr).toArray() : null, InternalUtils.check_arr_len(payment_hash, 32));
 332                 Reference.reachabilityFence(this);
 333                 Reference.reachabilityFence(payment_paths);
 334                 Reference.reachabilityFence(payment_hash);
 335                 if (ret >= 0 && ret <= 4096) { return null; }
 336                 Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 337                 return ret_hu_conv;
 338         }
 339
 340         /**
 341          * Creates an [`InvoiceBuilder`] for the request with the given required fields.
 342          *
 343          * Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
 344          * `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for `no-std` builds
 345          * where [`std::time::SystemTime`] is not available.
 346          *
 347          * The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
 348          * for the invoice.
 349          *
 350          * The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
 351          * must contain one or more elements ordered from most-preferred to least-preferred, if there's
 352          * a preference. Note, however, that any privacy is lost if a public node id was used for
 353          * [`Offer::signing_pubkey`].
 354          *
 355          * Errors if the request contains unknown required features.
 356          *
 357          * # Note
 358          *
 359          * If the originating [`Offer`] was created using [`OfferBuilder::deriving_signing_pubkey`],
 360          * then use [`InvoiceRequest::verify`] and [`VerifiedInvoiceRequest`] methods instead.
 361          *
 362          * [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at
 363          * [`OfferBuilder::deriving_signing_pubkey`]: crate::offers::offer::OfferBuilder::deriving_signing_pubkey
 364          */
 365         public Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ respond_with_no_std(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash, long created_at) {
 366                 long ret = bindings.VerifiedInvoiceRequest_respond_with_no_std(this.ptr, payment_paths != null ? Arrays.stream(payment_paths).mapToLong(payment_paths_conv_37 -> payment_paths_conv_37.ptr).toArray() : null, InternalUtils.check_arr_len(payment_hash, 32), created_at);
 367                 Reference.reachabilityFence(this);
 368                 Reference.reachabilityFence(payment_paths);
 369                 Reference.reachabilityFence(payment_hash);
 370                 Reference.reachabilityFence(created_at);
 371                 if (ret >= 0 && ret <= 4096) { return null; }
 372                 Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 373                 return ret_hu_conv;
 374         }
 375
 376         /**
 377          * Creates an [`InvoiceBuilder`] for the request using the given required fields and that uses
 378          * derived signing keys from the originating [`Offer`] to sign the [`Bolt12Invoice`]. Must use
 379          * the same [`ExpandedKey`] as the one used to create the offer.
 380          *
 381          * See [`InvoiceRequest::respond_with`] for further details.
 382          *
 383          * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 384          */
 385         public Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ respond_using_derived_keys(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash) {
 386                 long ret = bindings.VerifiedInvoiceRequest_respond_using_derived_keys(this.ptr, payment_paths != null ? Arrays.stream(payment_paths).mapToLong(payment_paths_conv_37 -> payment_paths_conv_37.ptr).toArray() : null, InternalUtils.check_arr_len(payment_hash, 32));
 387                 Reference.reachabilityFence(this);
 388                 Reference.reachabilityFence(payment_paths);
 389                 Reference.reachabilityFence(payment_hash);
 390                 if (ret >= 0 && ret <= 4096) { return null; }
 391                 Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 392                 return ret_hu_conv;
 393         }
 394
 395         /**
 396          * Creates an [`InvoiceBuilder`] for the request using the given required fields and that uses
 397          * derived signing keys from the originating [`Offer`] to sign the [`Bolt12Invoice`]. Must use
 398          * the same [`ExpandedKey`] as the one used to create the offer.
 399          *
 400          * See [`InvoiceRequest::respond_with_no_std`] for further details.
 401          *
 402          * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 403          */
 404         public Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ respond_using_derived_keys_no_std(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash, long created_at) {
 405                 long ret = bindings.VerifiedInvoiceRequest_respond_using_derived_keys_no_std(this.ptr, payment_paths != null ? Arrays.stream(payment_paths).mapToLong(payment_paths_conv_37 -> payment_paths_conv_37.ptr).toArray() : null, InternalUtils.check_arr_len(payment_hash, 32), created_at);
 406                 Reference.reachabilityFence(this);
 407                 Reference.reachabilityFence(payment_paths);
 408                 Reference.reachabilityFence(payment_hash);
 409                 Reference.reachabilityFence(created_at);
 410                 if (ret >= 0 && ret <= 4096) { return null; }
 411                 Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithDerivedSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 412                 return ret_hu_conv;
 413         }
 414
 415 }