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 * 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.
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); };
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 * 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.
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); };
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
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.
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.
82 * Returns a copy of the field.
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); };
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
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.
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.
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); };
115 long ret = bindings.RecipientOnionFields_clone_ptr(this.ptr);
116 Reference.reachabilityFence(this);
121 * Creates a copy of the RecipientOnionFields
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); };
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.
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); };
145 @Override public boolean equals(Object o) {
146 if (!(o instanceof RecipientOnionFields)) return false;
147 return this.eq((RecipientOnionFields)o);
150 * Serialize the RecipientOnionFields object into a byte array which can be read by RecipientOnionFields_read
152 public byte[] write() {
153 byte[] ret = bindings.RecipientOnionFields_write(this.ptr);
154 Reference.reachabilityFence(this);
159 * Read a RecipientOnionFields from a byte array, created by RecipientOnionFields_write
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);
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.
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); };
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`].
190 * [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
191 * [`RecipientOnionFields::secret_only`]: RecipientOnionFields::secret_only
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); };
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(())`.
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.
210 * See [`Self::custom_tlvs`] for more info.
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); };
223 * Gets the custom TLVs that will be sent or have been received.
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.
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`].
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;
245 return ret_conv_23_arr;