_ Git - ldk-java/blob - src/main/java/org/ldk/structs/InvoiceRequest.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` is a request for a [`Bolt12Invoice`] formulated from an [`Offer`].
  13  *
  14  * An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
  15  * specifies these such that its recipient can send an invoice for payment.
  16  *
  17  * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
  18  * [`Offer`]: crate::offers::offer::Offer
  19  */
  20 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  21 public class InvoiceRequest extends CommonBase {
  22         InvoiceRequest(Object _dummy, long ptr) { super(ptr); }
  23         @Override @SuppressWarnings("deprecation")
  24         protected void finalize() throws Throwable {
  25                 super.finalize();
  26                 if (ptr != 0) { bindings.InvoiceRequest_free(ptr); }
  27         }
  28
  29         long clone_ptr() {
  30                 long ret = bindings.InvoiceRequest_clone_ptr(this.ptr);
  31                 Reference.reachabilityFence(this);
  32                 return ret;
  33         }
  34
  35         /**
  36          * Creates a copy of the InvoiceRequest
  37          */
  38         public InvoiceRequest clone() {
  39                 long ret = bindings.InvoiceRequest_clone(this.ptr);
  40                 Reference.reachabilityFence(this);
  41                 if (ret >= 0 && ret <= 4096) { return null; }
  42                 org.ldk.structs.InvoiceRequest ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.InvoiceRequest(null, ret); }
  43                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  44                 return ret_hu_conv;
  45         }
  46
  47         /**
  48          * The chains that may be used when paying a requested invoice (e.g., bitcoin mainnet).
  49          * Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats)
  50          * for the selected chain.
  51          */
  52         public byte[][] chains() {
  53                 byte[][] ret = bindings.InvoiceRequest_chains(this.ptr);
  54                 Reference.reachabilityFence(this);
  55                 return ret;
  56         }
  57
  58         /**
  59          * Opaque bytes set by the originator. Useful for authentication and validating fields since it
  60          * is reflected in `invoice_request` messages along with all the other fields from the `offer`.
  61          */
  62         public Option_CVec_u8ZZ metadata() {
  63                 long ret = bindings.InvoiceRequest_metadata(this.ptr);
  64                 Reference.reachabilityFence(this);
  65                 if (ret >= 0 && ret <= 4096) { return null; }
  66                 org.ldk.structs.Option_CVec_u8ZZ ret_hu_conv = org.ldk.structs.Option_CVec_u8ZZ.constr_from_ptr(ret);
  67                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  68                 return ret_hu_conv;
  69         }
  70
  71         /**
  72          * The minimum amount required for a successful payment of a single item.
  73          */
  74         public Option_AmountZ amount() {
  75                 long ret = bindings.InvoiceRequest_amount(this.ptr);
  76                 Reference.reachabilityFence(this);
  77                 if (ret >= 0 && ret <= 4096) { return null; }
  78                 org.ldk.structs.Option_AmountZ ret_hu_conv = org.ldk.structs.Option_AmountZ.constr_from_ptr(ret);
  79                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  80                 return ret_hu_conv;
  81         }
  82
  83         /**
  84          * A complete description of the purpose of the payment. Intended to be displayed to the user
  85          * but with the caveat that it has not been verified in any way.
  86          *
  87          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
  88          */
  89         @Nullable
  90         public PrintableString description() {
  91                 long ret = bindings.InvoiceRequest_description(this.ptr);
  92                 Reference.reachabilityFence(this);
  93                 if (ret >= 0 && ret <= 4096) { return null; }
  94                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
  95                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  96                 return ret_hu_conv;
  97         }
  98
  99         /**
 100          * Features pertaining to the offer.
 101          */
 102         public OfferFeatures offer_features() {
 103                 long ret = bindings.InvoiceRequest_offer_features(this.ptr);
 104                 Reference.reachabilityFence(this);
 105                 if (ret >= 0 && ret <= 4096) { return null; }
 106                 org.ldk.structs.OfferFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OfferFeatures(null, ret); }
 107                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 108                 return ret_hu_conv;
 109         }
 110
 111         /**
 112          * Duration since the Unix epoch when an invoice should no longer be requested.
 113          *
 114          * If `None`, the offer does not expire.
 115          */
 116         public Option_u64Z absolute_expiry() {
 117                 long ret = bindings.InvoiceRequest_absolute_expiry(this.ptr);
 118                 Reference.reachabilityFence(this);
 119                 if (ret >= 0 && ret <= 4096) { return null; }
 120                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 121                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 122                 return ret_hu_conv;
 123         }
 124
 125         /**
 126          * The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
 127          * displayed to the user but with the caveat that it has not been verified in any way.
 128          *
 129          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 130          */
 131         @Nullable
 132         public PrintableString issuer() {
 133                 long ret = bindings.InvoiceRequest_issuer(this.ptr);
 134                 Reference.reachabilityFence(this);
 135                 if (ret >= 0 && ret <= 4096) { return null; }
 136                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 137                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 138                 return ret_hu_conv;
 139         }
 140
 141         /**
 142          * Paths to the recipient originating from publicly reachable nodes. Blinded paths provide
 143          * recipient privacy by obfuscating its node id.
 144          */
 145         public BlindedPath[] paths() {
 146                 long[] ret = bindings.InvoiceRequest_paths(this.ptr);
 147                 Reference.reachabilityFence(this);
 148                 int ret_conv_13_len = ret.length;
 149                 BlindedPath[] ret_conv_13_arr = new BlindedPath[ret_conv_13_len];
 150                 for (int n = 0; n < ret_conv_13_len; n++) {
 151                         long ret_conv_13 = ret[n];
 152                         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); }
 153                         if (ret_conv_13_hu_conv != null) { ret_conv_13_hu_conv.ptrs_to.add(this); };
 154                         ret_conv_13_arr[n] = ret_conv_13_hu_conv;
 155                 }
 156                 return ret_conv_13_arr;
 157         }
 158
 159         /**
 160          * The quantity of items supported.
 161          */
 162         public Quantity supported_quantity() {
 163                 long ret = bindings.InvoiceRequest_supported_quantity(this.ptr);
 164                 Reference.reachabilityFence(this);
 165                 if (ret >= 0 && ret <= 4096) { return null; }
 166                 org.ldk.structs.Quantity ret_hu_conv = org.ldk.structs.Quantity.constr_from_ptr(ret);
 167                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 168                 return ret_hu_conv;
 169         }
 170
 171         /**
 172          * The public key used by the recipient to sign invoices.
 173          *
 174          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 175          */
 176         @Nullable
 177         public byte[] signing_pubkey() {
 178                 byte[] ret = bindings.InvoiceRequest_signing_pubkey(this.ptr);
 179                 Reference.reachabilityFence(this);
 180                 return ret;
 181         }
 182
 183         /**
 184          * An unpredictable series of bytes, typically containing information about the derivation of
 185          * [`payer_id`].
 186          *
 187          * [`payer_id`]: Self::payer_id
 188          */
 189         public byte[] payer_metadata() {
 190                 byte[] ret = bindings.InvoiceRequest_payer_metadata(this.ptr);
 191                 Reference.reachabilityFence(this);
 192                 return ret;
 193         }
 194
 195         /**
 196          * A chain from [`Offer::chains`] that the offer is valid for.
 197          */
 198         public byte[] chain() {
 199                 byte[] ret = bindings.InvoiceRequest_chain(this.ptr);
 200                 Reference.reachabilityFence(this);
 201                 return ret;
 202         }
 203
 204         /**
 205          * The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
 206          * must be greater than or equal to [`Offer::amount`], converted if necessary.
 207          *
 208          * [`chain`]: Self::chain
 209          */
 210         public Option_u64Z amount_msats() {
 211                 long ret = bindings.InvoiceRequest_amount_msats(this.ptr);
 212                 Reference.reachabilityFence(this);
 213                 if (ret >= 0 && ret <= 4096) { return null; }
 214                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 215                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 216                 return ret_hu_conv;
 217         }
 218
 219         /**
 220          * Features pertaining to requesting an invoice.
 221          */
 222         public InvoiceRequestFeatures invoice_request_features() {
 223                 long ret = bindings.InvoiceRequest_invoice_request_features(this.ptr);
 224                 Reference.reachabilityFence(this);
 225                 if (ret >= 0 && ret <= 4096) { return null; }
 226                 org.ldk.structs.InvoiceRequestFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.InvoiceRequestFeatures(null, ret); }
 227                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 228                 return ret_hu_conv;
 229         }
 230
 231         /**
 232          * The quantity of the offer's item conforming to [`Offer::is_valid_quantity`].
 233          */
 234         public Option_u64Z quantity() {
 235                 long ret = bindings.InvoiceRequest_quantity(this.ptr);
 236                 Reference.reachabilityFence(this);
 237                 if (ret >= 0 && ret <= 4096) { return null; }
 238                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 239                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 240                 return ret_hu_conv;
 241         }
 242
 243         /**
 244          * A possibly transient pubkey used to sign the invoice request.
 245          */
 246         public byte[] payer_id() {
 247                 byte[] ret = bindings.InvoiceRequest_payer_id(this.ptr);
 248                 Reference.reachabilityFence(this);
 249                 return ret;
 250         }
 251
 252         /**
 253          * A payer-provided note which will be seen by the recipient and reflected back in the invoice
 254          * response.
 255          *
 256          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 257          */
 258         @Nullable
 259         public PrintableString payer_note() {
 260                 long ret = bindings.InvoiceRequest_payer_note(this.ptr);
 261                 Reference.reachabilityFence(this);
 262                 if (ret >= 0 && ret <= 4096) { return null; }
 263                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 264                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 265                 return ret_hu_conv;
 266         }
 267
 268         /**
 269          * Creates an [`InvoiceBuilder`] for the request with the given required fields and using the
 270          * [`Duration`] since [`std::time::SystemTime::UNIX_EPOCH`] as the creation time.
 271          *
 272          * See [`InvoiceRequest::respond_with_no_std`] for further details where the aforementioned
 273          * creation time is used for the `created_at` parameter.
 274          *
 275          * [`Duration`]: core::time::Duration
 276          */
 277         public Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ respond_with(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash) {
 278                 long ret = bindings.InvoiceRequest_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));
 279                 Reference.reachabilityFence(this);
 280                 Reference.reachabilityFence(payment_paths);
 281                 Reference.reachabilityFence(payment_hash);
 282                 if (ret >= 0 && ret <= 4096) { return null; }
 283                 Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 284                 return ret_hu_conv;
 285         }
 286
 287         /**
 288          * Creates an [`InvoiceBuilder`] for the request with the given required fields.
 289          *
 290          * Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
 291          * `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for `no-std` builds
 292          * where [`std::time::SystemTime`] is not available.
 293          *
 294          * The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
 295          * for the invoice.
 296          *
 297          * The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
 298          * must contain one or more elements ordered from most-preferred to least-preferred, if there's
 299          * a preference. Note, however, that any privacy is lost if a public node id was used for
 300          * [`Offer::signing_pubkey`].
 301          *
 302          * Errors if the request contains unknown required features.
 303          *
 304          * # Note
 305          *
 306          * If the originating [`Offer`] was created using [`OfferBuilder::deriving_signing_pubkey`],
 307          * then use [`InvoiceRequest::verify`] and [`VerifiedInvoiceRequest`] methods instead.
 308          *
 309          * [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at
 310          * [`OfferBuilder::deriving_signing_pubkey`]: crate::offers::offer::OfferBuilder::deriving_signing_pubkey
 311          */
 312         public Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ respond_with_no_std(TwoTuple_BlindedPayInfoBlindedPathZ[] payment_paths, byte[] payment_hash, long created_at) {
 313                 long ret = bindings.InvoiceRequest_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);
 314                 Reference.reachabilityFence(this);
 315                 Reference.reachabilityFence(payment_paths);
 316                 Reference.reachabilityFence(payment_hash);
 317                 Reference.reachabilityFence(created_at);
 318                 if (ret >= 0 && ret <= 4096) { return null; }
 319                 Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceWithExplicitSigningPubkeyBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 320                 return ret_hu_conv;
 321         }
 322
 323         /**
 324          * Verifies that the request was for an offer created using the given key. Returns the verified
 325          * request which contains the derived keys needed to sign a [`Bolt12Invoice`] for the request
 326          * if they could be extracted from the metadata.
 327          *
 328          * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 329          */
 330         public Result_VerifiedInvoiceRequestNoneZ verify(org.ldk.structs.ExpandedKey key) {
 331                 long ret = bindings.InvoiceRequest_verify(this.ptr, key.ptr);
 332                 Reference.reachabilityFence(this);
 333                 Reference.reachabilityFence(key);
 334                 if (ret >= 0 && ret <= 4096) { return null; }
 335                 Result_VerifiedInvoiceRequestNoneZ ret_hu_conv = Result_VerifiedInvoiceRequestNoneZ.constr_from_ptr(ret);
 336                 if (this != null) { this.ptrs_to.add(key); };
 337                 if (this != null) { this.ptrs_to.add(this); };
 338                 return ret_hu_conv;
 339         }
 340
 341         /**
 342          * Signature of the invoice request using [`payer_id`].
 343          *
 344          * [`payer_id`]: Self::payer_id
 345          */
 346         public byte[] signature() {
 347                 byte[] ret = bindings.InvoiceRequest_signature(this.ptr);
 348                 Reference.reachabilityFence(this);
 349                 return ret;
 350         }
 351
 352         /**
 353          * Serialize the InvoiceRequest object into a byte array which can be read by InvoiceRequest_read
 354          */
 355         public byte[] write() {
 356                 byte[] ret = bindings.InvoiceRequest_write(this.ptr);
 357                 Reference.reachabilityFence(this);
 358                 return ret;
 359         }
 360
 361 }