_ 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          * Note that for spontaneous payments most lightning nodes do not currently support MPP
  36          * receives, thus you should generally never be providing a secret here for spontaneous
  37          * payments.
  38          *
  39          * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
  40          */
  41         @Nullable
  42         public byte[] get_payment_secret() {
  43                 byte[] ret = bindings.RecipientOnionFields_get_payment_secret(this.ptr);
  44                 Reference.reachabilityFence(this);
  45                 return ret;
  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          * Note that for spontaneous payments most lightning nodes do not currently support MPP
  58          * receives, thus you should generally never be providing a secret here for spontaneous
  59          * payments.
  60          *
  61          * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None
  62          */
  63         public void set_payment_secret(@Nullable byte[] val) {
  64                 bindings.RecipientOnionFields_set_payment_secret(this.ptr, InternalUtils.check_arr_len(val, 32));
  65                 Reference.reachabilityFence(this);
  66                 Reference.reachabilityFence(val);
  67         }
  68
  69         /**
  70          * The payment metadata serves a similar purpose as [`Self::payment_secret`] but is of
  71          * arbitrary length. This gives recipients substantially more flexibility to receive
  72          * additional data.
  73          *
  74          * In LDK, while the [`Self::payment_secret`] is fixed based on an internal authentication
  75          * scheme to authenticate received payments against expected payments and invoices, this field
  76          * is not used in LDK for received payments, and can be used to store arbitrary data in
  77          * invoices which will be received with the payment.
  78          *
  79          * Note that this field was added to the lightning specification more recently than
  80          * [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
  81          * may not be supported as universally.
  82          *
  83          * Returns a copy of the field.
  84          */
  85         public Option_CVec_u8ZZ get_payment_metadata() {
  86                 long ret = bindings.RecipientOnionFields_get_payment_metadata(this.ptr);
  87                 Reference.reachabilityFence(this);
  88                 if (ret >= 0 && ret <= 4096) { return null; }
  89                 org.ldk.structs.Option_CVec_u8ZZ ret_hu_conv = org.ldk.structs.Option_CVec_u8ZZ.constr_from_ptr(ret);
  90                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
  91                 return ret_hu_conv;
  92         }
  93
  94         /**
  95          * The payment metadata serves a similar purpose as [`Self::payment_secret`] but is of
  96          * arbitrary length. This gives recipients substantially more flexibility to receive
  97          * additional data.
  98          *
  99          * In LDK, while the [`Self::payment_secret`] is fixed based on an internal authentication
 100          * scheme to authenticate received payments against expected payments and invoices, this field
 101          * is not used in LDK for received payments, and can be used to store arbitrary data in
 102          * invoices which will be received with the payment.
 103          *
 104          * Note that this field was added to the lightning specification more recently than
 105          * [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
 106          * may not be supported as universally.
 107          */
 108         public void set_payment_metadata(org.ldk.structs.Option_CVec_u8ZZ val) {
 109                 bindings.RecipientOnionFields_set_payment_metadata(this.ptr, val.ptr);
 110                 Reference.reachabilityFence(this);
 111                 Reference.reachabilityFence(val);
 112                 if (this != null) { this.ptrs_to.add(val); };
 113         }
 114
 115         /**
 116          * Constructs a new RecipientOnionFields given each field
 117          */
 118         public static RecipientOnionFields of(byte[] payment_secret_arg, org.ldk.structs.Option_CVec_u8ZZ payment_metadata_arg) {
 119                 long ret = bindings.RecipientOnionFields_new(InternalUtils.check_arr_len(payment_secret_arg, 32), payment_metadata_arg.ptr);
 120                 Reference.reachabilityFence(payment_secret_arg);
 121                 Reference.reachabilityFence(payment_metadata_arg);
 122                 if (ret >= 0 && ret <= 4096) { return null; }
 123                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 124                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 125                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(payment_metadata_arg); };
 126                 return ret_hu_conv;
 127         }
 128
 129         long clone_ptr() {
 130                 long ret = bindings.RecipientOnionFields_clone_ptr(this.ptr);
 131                 Reference.reachabilityFence(this);
 132                 return ret;
 133         }
 134
 135         /**
 136          * Creates a copy of the RecipientOnionFields
 137          */
 138         public RecipientOnionFields clone() {
 139                 long ret = bindings.RecipientOnionFields_clone(this.ptr);
 140                 Reference.reachabilityFence(this);
 141                 if (ret >= 0 && ret <= 4096) { return null; }
 142                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 143                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 144                 return ret_hu_conv;
 145         }
 146
 147         /**
 148          * Checks if two RecipientOnionFieldss contain equal inner contents.
 149          * This ignores pointers and is_owned flags and looks at the values in fields.
 150          * Two objects with NULL inner values will be considered "equal" here.
 151          */
 152         public boolean eq(org.ldk.structs.RecipientOnionFields b) {
 153                 boolean ret = bindings.RecipientOnionFields_eq(this.ptr, b == null ? 0 : b.ptr);
 154                 Reference.reachabilityFence(this);
 155                 Reference.reachabilityFence(b);
 156                 if (this != null) { this.ptrs_to.add(b); };
 157                 return ret;
 158         }
 159
 160         @Override public boolean equals(Object o) {
 161                 if (!(o instanceof RecipientOnionFields)) return false;
 162                 return this.eq((RecipientOnionFields)o);
 163         }
 164         /**
 165          * Serialize the RecipientOnionFields object into a byte array which can be read by RecipientOnionFields_read
 166          */
 167         public byte[] write() {
 168                 byte[] ret = bindings.RecipientOnionFields_write(this.ptr);
 169                 Reference.reachabilityFence(this);
 170                 return ret;
 171         }
 172
 173         /**
 174          * Read a RecipientOnionFields from a byte array, created by RecipientOnionFields_write
 175          */
 176         public static Result_RecipientOnionFieldsDecodeErrorZ read(byte[] ser) {
 177                 long ret = bindings.RecipientOnionFields_read(ser);
 178                 Reference.reachabilityFence(ser);
 179                 if (ret >= 0 && ret <= 4096) { return null; }
 180                 Result_RecipientOnionFieldsDecodeErrorZ ret_hu_conv = Result_RecipientOnionFieldsDecodeErrorZ.constr_from_ptr(ret);
 181                 return ret_hu_conv;
 182         }
 183
 184         /**
 185          * Creates a [`RecipientOnionFields`] from only a [`PaymentSecret`]. This is the most common
 186          * set of onion fields for today's BOLT11 invoices - most nodes require a [`PaymentSecret`]
 187          * but do not require or provide any further data.
 188          */
 189         public static RecipientOnionFields secret_only(byte[] payment_secret) {
 190                 long ret = bindings.RecipientOnionFields_secret_only(InternalUtils.check_arr_len(payment_secret, 32));
 191                 Reference.reachabilityFence(payment_secret);
 192                 if (ret >= 0 && ret <= 4096) { return null; }
 193                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 194                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 195                 return ret_hu_conv;
 196         }
 197
 198         /**
 199          * Creates a new [`RecipientOnionFields`] with no fields. This generally does not create
 200          * payable HTLCs except for spontaneous payments, i.e. this should generally only be used for
 201          * calls to [`ChannelManager::send_spontaneous_payment`].
 202          *
 203          * [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
 204          */
 205         public static RecipientOnionFields spontaneous_empty() {
 206                 long ret = bindings.RecipientOnionFields_spontaneous_empty();
 207                 if (ret >= 0 && ret <= 4096) { return null; }
 208                 org.ldk.structs.RecipientOnionFields ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.RecipientOnionFields(null, ret); }
 209                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 210                 return ret_hu_conv;
 211         }
 212
 213 }