_ Git - ldk-java/blob - src/main/java/org/ldk/structs/Offer.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 `Offer` is a potentially long-lived proposal for payment of a good or service.
  13  *
  14  * An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
  15  * customer may request an [`Bolt12Invoice`] for a specific quantity and using an amount sufficient
  16  * to cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
  17  *
  18  * Offers may be denominated in currency other than bitcoin but are ultimately paid using the
  19  * latter.
  20  *
  21  * Through the use of [`BlindedPath`]s, offers provide recipient privacy.
  22  *
  23  * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
  24  * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
  25  */
  26 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  27 public class Offer extends CommonBase {
  28         Offer(Object _dummy, long ptr) { super(ptr); }
  29         @Override @SuppressWarnings("deprecation")
  30         protected void finalize() throws Throwable {
  31                 super.finalize();
  32                 if (ptr != 0) { bindings.Offer_free(ptr); }
  33         }
  34
  35         long clone_ptr() {
  36                 long ret = bindings.Offer_clone_ptr(this.ptr);
  37                 Reference.reachabilityFence(this);
  38                 return ret;
  39         }
  40
  41         /**
  42          * Creates a copy of the Offer
  43          */
  44         public Offer clone() {
  45                 long ret = bindings.Offer_clone(this.ptr);
  46                 Reference.reachabilityFence(this);
  47                 if (ret >= 0 && ret <= 4096) { return null; }
  48                 org.ldk.structs.Offer ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.Offer(null, ret); }
  49                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  50                 return ret_hu_conv;
  51         }
  52
  53         /**
  54          * The chains that may be used when paying a requested invoice (e.g., bitcoin mainnet).
  55          * Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats)
  56          * for the selected chain.
  57          */
  58         public byte[][] chains() {
  59                 byte[][] ret = bindings.Offer_chains(this.ptr);
  60                 Reference.reachabilityFence(this);
  61                 return ret;
  62         }
  63
  64         /**
  65          * Opaque bytes set by the originator. Useful for authentication and validating fields since it
  66          * is reflected in `invoice_request` messages along with all the other fields from the `offer`.
  67          */
  68         public Option_CVec_u8ZZ metadata() {
  69                 long ret = bindings.Offer_metadata(this.ptr);
  70                 Reference.reachabilityFence(this);
  71                 if (ret >= 0 && ret <= 4096) { return null; }
  72                 org.ldk.structs.Option_CVec_u8ZZ ret_hu_conv = org.ldk.structs.Option_CVec_u8ZZ.constr_from_ptr(ret);
  73                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  74                 return ret_hu_conv;
  75         }
  76
  77         /**
  78          * The minimum amount required for a successful payment of a single item.
  79          */
  80         public Option_AmountZ amount() {
  81                 long ret = bindings.Offer_amount(this.ptr);
  82                 Reference.reachabilityFence(this);
  83                 if (ret >= 0 && ret <= 4096) { return null; }
  84                 org.ldk.structs.Option_AmountZ ret_hu_conv = org.ldk.structs.Option_AmountZ.constr_from_ptr(ret);
  85                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  86                 return ret_hu_conv;
  87         }
  88
  89         /**
  90          * A complete description of the purpose of the payment. Intended to be displayed to the user
  91          * but with the caveat that it has not been verified in any way.
  92          *
  93          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
  94          */
  95         @Nullable
  96         public PrintableString description() {
  97                 long ret = bindings.Offer_description(this.ptr);
  98                 Reference.reachabilityFence(this);
  99                 if (ret >= 0 && ret <= 4096) { return null; }
 100                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 101                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 102                 return ret_hu_conv;
 103         }
 104
 105         /**
 106          * Features pertaining to the offer.
 107          */
 108         public OfferFeatures offer_features() {
 109                 long ret = bindings.Offer_offer_features(this.ptr);
 110                 Reference.reachabilityFence(this);
 111                 if (ret >= 0 && ret <= 4096) { return null; }
 112                 org.ldk.structs.OfferFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OfferFeatures(null, ret); }
 113                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 114                 return ret_hu_conv;
 115         }
 116
 117         /**
 118          * Duration since the Unix epoch when an invoice should no longer be requested.
 119          *
 120          * If `None`, the offer does not expire.
 121          */
 122         public Option_u64Z absolute_expiry() {
 123                 long ret = bindings.Offer_absolute_expiry(this.ptr);
 124                 Reference.reachabilityFence(this);
 125                 if (ret >= 0 && ret <= 4096) { return null; }
 126                 org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret);
 127                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 128                 return ret_hu_conv;
 129         }
 130
 131         /**
 132          * The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
 133          * displayed to the user but with the caveat that it has not been verified in any way.
 134          *
 135          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 136          */
 137         @Nullable
 138         public PrintableString issuer() {
 139                 long ret = bindings.Offer_issuer(this.ptr);
 140                 Reference.reachabilityFence(this);
 141                 if (ret >= 0 && ret <= 4096) { return null; }
 142                 org.ldk.structs.PrintableString ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PrintableString(null, ret); }
 143                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 144                 return ret_hu_conv;
 145         }
 146
 147         /**
 148          * Paths to the recipient originating from publicly reachable nodes. Blinded paths provide
 149          * recipient privacy by obfuscating its node id.
 150          */
 151         public BlindedPath[] paths() {
 152                 long[] ret = bindings.Offer_paths(this.ptr);
 153                 Reference.reachabilityFence(this);
 154                 int ret_conv_13_len = ret.length;
 155                 BlindedPath[] ret_conv_13_arr = new BlindedPath[ret_conv_13_len];
 156                 for (int n = 0; n < ret_conv_13_len; n++) {
 157                         long ret_conv_13 = ret[n];
 158                         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); }
 159                         if (ret_conv_13_hu_conv != null) { ret_conv_13_hu_conv.ptrs_to.add(this); };
 160                         ret_conv_13_arr[n] = ret_conv_13_hu_conv;
 161                 }
 162                 return ret_conv_13_arr;
 163         }
 164
 165         /**
 166          * The quantity of items supported.
 167          */
 168         public Quantity supported_quantity() {
 169                 long ret = bindings.Offer_supported_quantity(this.ptr);
 170                 Reference.reachabilityFence(this);
 171                 if (ret >= 0 && ret <= 4096) { return null; }
 172                 org.ldk.structs.Quantity ret_hu_conv = org.ldk.structs.Quantity.constr_from_ptr(ret);
 173                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 174                 return ret_hu_conv;
 175         }
 176
 177         /**
 178          * The public key used by the recipient to sign invoices.
 179          *
 180          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 181          */
 182         @Nullable
 183         public byte[] signing_pubkey() {
 184                 byte[] ret = bindings.Offer_signing_pubkey(this.ptr);
 185                 Reference.reachabilityFence(this);
 186                 return ret;
 187         }
 188
 189         /**
 190          * Returns the id of the offer.
 191          */
 192         public OfferId id() {
 193                 long ret = bindings.Offer_id(this.ptr);
 194                 Reference.reachabilityFence(this);
 195                 if (ret >= 0 && ret <= 4096) { return null; }
 196                 org.ldk.structs.OfferId ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OfferId(null, ret); }
 197                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 198                 return ret_hu_conv;
 199         }
 200
 201         /**
 202          * Returns whether the given chain is supported by the offer.
 203          */
 204         public boolean supports_chain(byte[] chain) {
 205                 boolean ret = bindings.Offer_supports_chain(this.ptr, InternalUtils.check_arr_len(chain, 32));
 206                 Reference.reachabilityFence(this);
 207                 Reference.reachabilityFence(chain);
 208                 return ret;
 209         }
 210
 211         /**
 212          * Whether the offer has expired.
 213          */
 214         public boolean is_expired() {
 215                 boolean ret = bindings.Offer_is_expired(this.ptr);
 216                 Reference.reachabilityFence(this);
 217                 return ret;
 218         }
 219
 220         /**
 221          * Whether the offer has expired given the duration since the Unix epoch.
 222          */
 223         public boolean is_expired_no_std(long duration_since_epoch) {
 224                 boolean ret = bindings.Offer_is_expired_no_std(this.ptr, duration_since_epoch);
 225                 Reference.reachabilityFence(this);
 226                 Reference.reachabilityFence(duration_since_epoch);
 227                 return ret;
 228         }
 229
 230         /**
 231          * Returns whether the given quantity is valid for the offer.
 232          */
 233         public boolean is_valid_quantity(long quantity) {
 234                 boolean ret = bindings.Offer_is_valid_quantity(this.ptr, quantity);
 235                 Reference.reachabilityFence(this);
 236                 Reference.reachabilityFence(quantity);
 237                 return ret;
 238         }
 239
 240         /**
 241          * Returns whether a quantity is expected in an [`InvoiceRequest`] for the offer.
 242          *
 243          * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 244          */
 245         public boolean expects_quantity() {
 246                 boolean ret = bindings.Offer_expects_quantity(this.ptr);
 247                 Reference.reachabilityFence(this);
 248                 return ret;
 249         }
 250
 251         /**
 252          * Similar to [`Offer::request_invoice`] except it:
 253          * - derives the [`InvoiceRequest::payer_id`] such that a different key can be used for each
 254          * request,
 255          * - sets [`InvoiceRequest::payer_metadata`] when [`InvoiceRequestBuilder::build`] is called
 256          * such that it can be used by [`Bolt12Invoice::verify`] to determine if the invoice was
 257          * requested using a base [`ExpandedKey`] from which the payer id was derived, and
 258          * - includes the [`PaymentId`] encrypted in [`InvoiceRequest::payer_metadata`] so that it can
 259          * be used when sending the payment for the requested invoice.
 260          *
 261          * Useful to protect the sender's privacy.
 262          *
 263          * [`InvoiceRequest::payer_id`]: crate::offers::invoice_request::InvoiceRequest::payer_id
 264          * [`InvoiceRequest::payer_metadata`]: crate::offers::invoice_request::InvoiceRequest::payer_metadata
 265          * [`Bolt12Invoice::verify`]: crate::offers::invoice::Bolt12Invoice::verify
 266          * [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey
 267          */
 268         public Result_InvoiceRequestWithDerivedPayerIdBuilderBolt12SemanticErrorZ request_invoice_deriving_payer_id(org.ldk.structs.ExpandedKey expanded_key, org.ldk.structs.EntropySource entropy_source, byte[] payment_id) {
 269                 long ret = bindings.Offer_request_invoice_deriving_payer_id(this.ptr, expanded_key.ptr, entropy_source.ptr, InternalUtils.check_arr_len(payment_id, 32));
 270                 Reference.reachabilityFence(this);
 271                 Reference.reachabilityFence(expanded_key);
 272                 Reference.reachabilityFence(entropy_source);
 273                 Reference.reachabilityFence(payment_id);
 274                 if (ret >= 0 && ret <= 4096) { return null; }
 275                 Result_InvoiceRequestWithDerivedPayerIdBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceRequestWithDerivedPayerIdBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 276                 if (this != null) { this.ptrs_to.add(expanded_key); };
 277                 if (this != null) { this.ptrs_to.add(entropy_source); };
 278                 return ret_hu_conv;
 279         }
 280
 281         /**
 282          * Similar to [`Offer::request_invoice_deriving_payer_id`] except uses `payer_id` for the
 283          * [`InvoiceRequest::payer_id`] instead of deriving a different key for each request.
 284          *
 285          * Useful for recurring payments using the same `payer_id` with different invoices.
 286          *
 287          * [`InvoiceRequest::payer_id`]: crate::offers::invoice_request::InvoiceRequest::payer_id
 288          */
 289         public Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ request_invoice_deriving_metadata(byte[] payer_id, org.ldk.structs.ExpandedKey expanded_key, org.ldk.structs.EntropySource entropy_source, byte[] payment_id) {
 290                 long ret = bindings.Offer_request_invoice_deriving_metadata(this.ptr, InternalUtils.check_arr_len(payer_id, 33), expanded_key.ptr, entropy_source.ptr, InternalUtils.check_arr_len(payment_id, 32));
 291                 Reference.reachabilityFence(this);
 292                 Reference.reachabilityFence(payer_id);
 293                 Reference.reachabilityFence(expanded_key);
 294                 Reference.reachabilityFence(entropy_source);
 295                 Reference.reachabilityFence(payment_id);
 296                 if (ret >= 0 && ret <= 4096) { return null; }
 297                 Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 298                 if (this != null) { this.ptrs_to.add(expanded_key); };
 299                 if (this != null) { this.ptrs_to.add(entropy_source); };
 300                 return ret_hu_conv;
 301         }
 302
 303         /**
 304          * Creates an [`InvoiceRequestBuilder`] for the offer with the given `metadata` and `payer_id`,
 305          * which will be reflected in the `Bolt12Invoice` response.
 306          *
 307          * The `metadata` is useful for including information about the derivation of `payer_id` such
 308          * that invoice response handling can be stateless. Also serves as payer-provided entropy while
 309          * hashing in the signature calculation.
 310          *
 311          * This should not leak any information such as by using a simple BIP-32 derivation path.
 312          * Otherwise, payments may be correlated.
 313          *
 314          * Errors if the offer contains unknown required features.
 315          *
 316          * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 317          */
 318         public Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ request_invoice(byte[] metadata, byte[] payer_id) {
 319                 long ret = bindings.Offer_request_invoice(this.ptr, metadata, InternalUtils.check_arr_len(payer_id, 33));
 320                 Reference.reachabilityFence(this);
 321                 Reference.reachabilityFence(metadata);
 322                 Reference.reachabilityFence(payer_id);
 323                 if (ret >= 0 && ret <= 4096) { return null; }
 324                 Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ ret_hu_conv = Result_InvoiceRequestWithExplicitPayerIdBuilderBolt12SemanticErrorZ.constr_from_ptr(ret);
 325                 return ret_hu_conv;
 326         }
 327
 328         /**
 329          * Generates a non-cryptographic 64-bit hash of the Offer.
 330          */
 331         public long hash() {
 332                 long ret = bindings.Offer_hash(this.ptr);
 333                 Reference.reachabilityFence(this);
 334                 return ret;
 335         }
 336
 337         @Override public int hashCode() {
 338                 return (int)this.hash();
 339         }
 340         /**
 341          * Serialize the Offer object into a byte array which can be read by Offer_read
 342          */
 343         public byte[] write() {
 344                 byte[] ret = bindings.Offer_write(this.ptr);
 345                 Reference.reachabilityFence(this);
 346                 return ret;
 347         }
 348
 349         /**
 350          * Read a Offer object from a string
 351          */
 352         public static Result_OfferBolt12ParseErrorZ from_str(java.lang.String s) {
 353                 long ret = bindings.Offer_from_str(s);
 354                 Reference.reachabilityFence(s);
 355                 if (ret >= 0 && ret <= 4096) { return null; }
 356                 Result_OfferBolt12ParseErrorZ ret_hu_conv = Result_OfferBolt12ParseErrorZ.constr_from_ptr(ret);
 357                 return ret_hu_conv;
 358         }
 359
 360         /**
 361          * Get the string representation of a Offer object
 362          */
 363         public String to_str() {
 364                 String ret = bindings.Offer_to_str(this.ptr);
 365                 Reference.reachabilityFence(this);
 366                 return ret;
 367         }
 368
 369 }