_ Git - ldk-java/blob - src/main/java/org/ldk/structs/RecipientOnionFields.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  * Information which is provided, encrypted, to the payment recipient when sending HTLCs.
  13  *
  14  * This should generally be constructed with data communicated to us from the recipient (via a
  15  * BOLT11 or BOLT12 invoice).
  16  */
  17 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  18 public class RecipientOnionFields extends CommonBase {
  19         RecipientOnionFields(Object _dummy, long ptr) { super(ptr); }
  20         @Override @SuppressWarnings("deprecation")
  21         protected void finalize() throws Throwable {
  22                 super.finalize();
  23                 if (ptr != 0) { bindings.RecipientOnionFields_free(ptr); }
  24         }
  25
  26         /**
  27          * The [`PaymentSecret`] is an arbitrary 32 bytes provided by the recipient for us to repeat
  28          * in the onion. It is unrelated to `payment_hash` (or [`PaymentPreimage`]) and exists to
  29          * authenticate the sender to the recipient and prevent payment-probing (deanonymization)
  30          * attacks.
  31          *
  32          * If you do not have one, the [`Route`] you pay over must not contain multiple paths as
  33          * multi-path payments require a recipient-provided secret.
  34          *
  35          * Some implementations may reject spontaneous payments with payment secrets, so you may only
  36          * want to provide a secret for a spontaneous payment if MPP is needed and you know your
  37          * recipient will not reject it.
  38          */
  39         public Option_ThirtyTwoBytesZ get_payment_secret() {
  40                 long ret = bindings.RecipientOnionFields_get_payment_secret(this.ptr);
  41                 Reference.reachabilityFence(this);
  42                 if (ret >= 0 && ret <= 4096) { return null; }
  43                 org.ldk.structs.Option_ThirtyTwoBytesZ ret_hu_conv = org.ldk.structs.Option_ThirtyTwoBytesZ.constr_from_ptr(ret);
  44                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  45                 return ret_hu_conv;
  46         }
  47
  48         /**
  49          * The [`PaymentSecret`] is an arbitrary 32 bytes provided by the recipient for us to repeat
  50          * in the onion. It is unrelated to `payment_hash` (or [`PaymentPreimage`]) and exists to
  51          * authenticate the sender to the recipient and prevent payment-probing (deanonymization)
  52          * attacks.
  53          *
  54          * If you do not have one, the [`Route`] you pay over must not contain multiple paths as
  55          * multi-path payments require a recipient-provided secret.
  56          *
  57          * Some implementations may reject spontaneous payments with payment secrets, so you may only
  58          * want to provide a secret for a spontaneous payment if MPP is needed and you know your
  59          * recipient will not reject it.
  60          */
  61         public void set_payment_secret(org.ldk.structs.Option_ThirtyTwoBytesZ val) {
  62                 bindings.RecipientOnionFields_set_payment_secret(this.ptr, val.ptr);
  63                 Reference.reachabilityFence(this);
  64                 Reference.reachabilityFence(val);
  65                 if (this != null) { this.ptrs_to.add(val); };
  66         }
  67
  68         /**
  69          * The payment metadata serves a similar purpose as [`Self::payment_secret`] but is of
  70          * arbitrary length. This gives recipients substantially more flexibility to receive
  71          * additional data.
  72          *
  73          * In LDK, while the [`Self::payment_secret`] is fixed based on an internal authentication
  74          * scheme to authenticate received payments against expected payments and invoices, this field
  75          * is not used in LDK for received payments, and can be used to store arbitrary data in
  76          * invoices which will be received with the payment.
  77          *
  78          * Note that this field was added to the lightning specification more recently than
  79          * [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
  80          * may not be supported as universally.
  81          *
  82          * Returns a copy of the field.
  83          */
  84         public Option_CVec_u8ZZ get_payment_metadata() {
  85                 long ret = bindings.RecipientOnionFields_get_payment_metadata(this.ptr);
  86                 Reference.reachabilityFence(this);
  87                 if (ret >= 0 && ret <= 4096) { return null; }
  88                 org.ldk.structs.Option_CVec_u8ZZ ret_hu_conv = org.ldk.structs.Option_CVec_u8ZZ.constr_from_ptr(ret);
  89                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  90                 return ret_hu_conv;
  91         }
  92
  93         /**
  94          * The payment metadata serves a similar purpose as [`Self::payment_secret`] but is of
  95          * arbitrary length. This gives recipients substantially more flexibility to receive
  96          * additional data.
  97          *
  98          * In LDK, while the [`Self::payment_secret`] is fixed based on an internal authentication
  99          * scheme to authenticate received payments against expected payments and invoices, this field
 100          * is not used in LDK for received payments, and can be used to store arbitrary data in
 101          * invoices which will be received with the payment.
 102          *
 103          * Note that this field was added to the lightning specification more recently than
 104          * [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
 105          * may not be supported as universally.
 106          */
 107         public void set_payment_metadata(org.ldk.structs.Option_CVec_u8ZZ val) {
 108                 bindings.RecipientOnionFields_set_payment_metadata(this.ptr, val.ptr);
 109                 Reference.reachabilityFence(this);
 110                 Reference.reachabilityFence(val);
 111                 if (this != null) { this.ptrs_to.add(val); };
 112         }
 113
 114         long clone_ptr() {
 115                 long ret = bindings.RecipientOnionFields_clone_ptr(this.ptr);
 116                 Reference.reachabilityFence(this);
 117                 return ret;
 118         }
 119
 120         /**
 121          * Creates a copy of the RecipientOnionFields
 122          */
 123         public RecipientOnionFields clone() {
 124                 long ret = bindings.RecipientOnionFields_clone(this.ptr);
 125                 Reference.reachabilityFence(this);
 126                 if (ret >= 0 && ret <= 4096) { return null; }
 127                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 128                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 129                 return ret_hu_conv;
 130         }
 131
 132         /**
 133          * Checks if two RecipientOnionFieldss contain equal inner contents.
 134          * This ignores pointers and is_owned flags and looks at the values in fields.
 135          * Two objects with NULL inner values will be considered "equal" here.
 136          */
 137         public boolean eq(org.ldk.structs.RecipientOnionFields b) {
 138                 boolean ret = bindings.RecipientOnionFields_eq(this.ptr, b == null ? 0 : b.ptr);
 139                 Reference.reachabilityFence(this);
 140                 Reference.reachabilityFence(b);
 141                 if (this != null) { this.ptrs_to.add(b); };
 142                 return ret;
 143         }
 144
 145         @Override public boolean equals(Object o) {
 146                 if (!(o instanceof RecipientOnionFields)) return false;
 147                 return this.eq((RecipientOnionFields)o);
 148         }
 149         /**
 150          * Serialize the RecipientOnionFields object into a byte array which can be read by RecipientOnionFields_read
 151          */
 152         public byte[] write() {
 153                 byte[] ret = bindings.RecipientOnionFields_write(this.ptr);
 154                 Reference.reachabilityFence(this);
 155                 return ret;
 156         }
 157
 158         /**
 159          * Read a RecipientOnionFields from a byte array, created by RecipientOnionFields_write
 160          */
 161         public static Result_RecipientOnionFieldsDecodeErrorZ read(byte[] ser) {
 162                 long ret = bindings.RecipientOnionFields_read(ser);
 163                 Reference.reachabilityFence(ser);
 164                 if (ret >= 0 && ret <= 4096) { return null; }
 165                 Result_RecipientOnionFieldsDecodeErrorZ ret_hu_conv = Result_RecipientOnionFieldsDecodeErrorZ.constr_from_ptr(ret);
 166                 return ret_hu_conv;
 167         }
 168
 169         /**
 170          * Creates a [`RecipientOnionFields`] from only a [`PaymentSecret`]. This is the most common
 171          * set of onion fields for today's BOLT11 invoices - most nodes require a [`PaymentSecret`]
 172          * but do not require or provide any further data.
 173          */
 174         public static RecipientOnionFields secret_only(byte[] payment_secret) {
 175                 long ret = bindings.RecipientOnionFields_secret_only(InternalUtils.check_arr_len(payment_secret, 32));
 176                 Reference.reachabilityFence(payment_secret);
 177                 if (ret >= 0 && ret <= 4096) { return null; }
 178                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 179                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 180                 return ret_hu_conv;
 181         }
 182
 183         /**
 184          * Creates a new [`RecipientOnionFields`] with no fields. This generally does not create
 185          * payable HTLCs except for single-path spontaneous payments, i.e. this should generally
 186          * only be used for calls to [`ChannelManager::send_spontaneous_payment`]. If you are sending
 187          * a spontaneous MPP this will not work as all MPP require payment secrets; you may
 188          * instead want to use [`RecipientOnionFields::secret_only`].
 189          *
 190          * [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
 191          * [`RecipientOnionFields::secret_only`]: RecipientOnionFields::secret_only
 192          */
 193         public static RecipientOnionFields spontaneous_empty() {
 194                 long ret = bindings.RecipientOnionFields_spontaneous_empty();
 195                 if (ret >= 0 && ret <= 4096) { return null; }
 196                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 197                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 198                 return ret_hu_conv;
 199         }
 200
 201         /**
 202          * Creates a new [`RecipientOnionFields`] from an existing one, adding custom TLVs. Each
 203          * TLV is provided as a `(u64, Vec<u8>)` for the type number and serialized value
 204          * respectively. TLV type numbers must be unique and within the range
 205          * reserved for custom types, i.e. >= 2^16, otherwise this method will return `Err(())`.
 206          *
 207          * This method will also error for types in the experimental range which have been
 208          * standardized within the protocol, which only includes 5482373484 (keysend) for now.
 209          *
 210          * See [`Self::custom_tlvs`] for more info.
 211          */
 212         public Result_RecipientOnionFieldsNoneZ with_custom_tlvs(TwoTuple_u64CVec_u8ZZ[] custom_tlvs) {
 213                 long ret = bindings.RecipientOnionFields_with_custom_tlvs(this.ptr, custom_tlvs != null ? Arrays.stream(custom_tlvs).mapToLong(custom_tlvs_conv_23 -> custom_tlvs_conv_23 != null ? custom_tlvs_conv_23.ptr : 0).toArray() : null);
 214                 Reference.reachabilityFence(this);
 215                 Reference.reachabilityFence(custom_tlvs);
 216                 if (ret >= 0 && ret <= 4096) { return null; }
 217                 Result_RecipientOnionFieldsNoneZ ret_hu_conv = Result_RecipientOnionFieldsNoneZ.constr_from_ptr(ret);
 218                 if (this != null) { this.ptrs_to.add(this); };
 219                 return ret_hu_conv;
 220         }
 221
 222         /**
 223          * Gets the custom TLVs that will be sent or have been received.
 224          *
 225          * Custom TLVs allow sending extra application-specific data with a payment. They provide
 226          * additional flexibility on top of payment metadata, as while other implementations may
 227          * require `payment_metadata` to reflect metadata provided in an invoice, custom TLVs
 228          * do not have this restriction.
 229          *
 230          * Note that if this field is non-empty, it will contain strictly increasing TLVs, each
 231          * represented by a `(u64, Vec<u8>)` for its type number and serialized value respectively.
 232          * This is validated when setting this field using [`Self::with_custom_tlvs`].
 233          */
 234         public TwoTuple_u64CVec_u8ZZ[] custom_tlvs() {
 235                 long[] ret = bindings.RecipientOnionFields_custom_tlvs(this.ptr);
 236                 Reference.reachabilityFence(this);
 237                 int ret_conv_23_len = ret.length;
 238                 TwoTuple_u64CVec_u8ZZ[] ret_conv_23_arr = new TwoTuple_u64CVec_u8ZZ[ret_conv_23_len];
 239                 for (int x = 0; x < ret_conv_23_len; x++) {
 240                         long ret_conv_23 = ret[x];
 241                         TwoTuple_u64CVec_u8ZZ ret_conv_23_hu_conv = new TwoTuple_u64CVec_u8ZZ(null, ret_conv_23);
 242                         if (ret_conv_23_hu_conv != null) { ret_conv_23_hu_conv.ptrs_to.add(this); };
 243                         ret_conv_23_arr[x] = ret_conv_23_hu_conv;
 244                 }
 245                 return ret_conv_23_arr;
 246         }
 247
 248 }