1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
12 * Information which is provided, encrypted, to the payment recipient when sending HTLCs.
14 * This should generally be constructed with data communicated to us from the recipient (via a
15 * BOLT11 or BOLT12 invoice).
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 {
23 if (ptr != 0) { bindings.RecipientOnionFields_free(ptr); }
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)
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.
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
39 * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
42 public byte[] get_payment_secret() {
43 byte[] ret = bindings.RecipientOnionFields_get_payment_secret(this.ptr);
44 Reference.reachabilityFence(this);
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)
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.
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
61 * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None
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);
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
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.
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.
83 * Returns a copy of the field.
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); };
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
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.
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.
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); };
116 * Constructs a new RecipientOnionFields given each field
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); };
130 long ret = bindings.RecipientOnionFields_clone_ptr(this.ptr);
131 Reference.reachabilityFence(this);
136 * Creates a copy of the RecipientOnionFields
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); };
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.
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); };
160 @Override public boolean equals(Object o) {
161 if (!(o instanceof RecipientOnionFields)) return false;
162 return this.eq((RecipientOnionFields)o);
165 * Serialize the RecipientOnionFields object into a byte array which can be read by RecipientOnionFields_read
167 public byte[] write() {
168 byte[] ret = bindings.RecipientOnionFields_write(this.ptr);
169 Reference.reachabilityFence(this);
174 * Read a RecipientOnionFields from a byte array, created by RecipientOnionFields_write
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);
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.
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); };
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`].
203 * [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
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); };