X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FPaymentParameters.java;h=edf8d24c66c2206f75b945b2374d140793096f12;hb=2bb592fb946e316dba9f4d1123f8ac72ff4e9bf8;hp=6060d53a61065376abedf415d6d6adb0511b597d;hpb=293bcee787de3eb181b82175a1784a4ef311e012;p=ldk-java diff --git a/src/main/java/org/ldk/structs/PaymentParameters.java b/src/main/java/org/ldk/structs/PaymentParameters.java index 6060d53a..edf8d24c 100644 --- a/src/main/java/org/ldk/structs/PaymentParameters.java +++ b/src/main/java/org/ldk/structs/PaymentParameters.java @@ -9,7 +9,7 @@ import javax.annotation.Nullable; /** - * The recipient of a payment. + * Information used to route a payment. */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class PaymentParameters extends CommonBase { @@ -21,142 +21,175 @@ public class PaymentParameters extends CommonBase { } /** - * The node id of the payee. + * Information about the payee, such as their features and route hints for their channels. */ - public byte[] get_payee_pubkey() { - byte[] ret = bindings.PaymentParameters_get_payee_pubkey(this.ptr); + public Payee get_payee() { + long ret = bindings.PaymentParameters_get_payee(this.ptr); Reference.reachabilityFence(this); - return ret; + if (ret >= 0 && ret <= 4096) { return null; } + org.ldk.structs.Payee ret_hu_conv = org.ldk.structs.Payee.constr_from_ptr(ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + return ret_hu_conv; } /** - * The node id of the payee. + * Information about the payee, such as their features and route hints for their channels. */ - public void set_payee_pubkey(byte[] val) { - bindings.PaymentParameters_set_payee_pubkey(this.ptr, InternalUtils.check_arr_len(val, 33)); + public void set_payee(org.ldk.structs.Payee val) { + bindings.PaymentParameters_set_payee(this.ptr, val.ptr); Reference.reachabilityFence(this); Reference.reachabilityFence(val); + if (this != null) { this.ptrs_to.add(val); }; } /** - * Features supported by the payee. - * - * May be set from the payee's invoice or via [`for_keysend`]. May be `None` if the invoice - * does not contain any features. - * - * [`for_keysend`]: Self::for_keysend - * - * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + * Expiration of a payment to the payee, in seconds relative to the UNIX epoch. */ - @Nullable - public InvoiceFeatures get_features() { - long ret = bindings.PaymentParameters_get_features(this.ptr); + public Option_u64Z get_expiry_time() { + long ret = bindings.PaymentParameters_get_expiry_time(this.ptr); Reference.reachabilityFence(this); if (ret >= 0 && ret <= 4096) { return null; } - org.ldk.structs.InvoiceFeatures ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.InvoiceFeatures(null, ret); } - ret_hu_conv.ptrs_to.add(this); + org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; return ret_hu_conv; } /** - * Features supported by the payee. - * - * May be set from the payee's invoice or via [`for_keysend`]. May be `None` if the invoice - * does not contain any features. - * - * [`for_keysend`]: Self::for_keysend - * - * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None + * Expiration of a payment to the payee, in seconds relative to the UNIX epoch. */ - public void set_features(@Nullable InvoiceFeatures val) { - bindings.PaymentParameters_set_features(this.ptr, val == null ? 0 : val.ptr & ~1); + public void set_expiry_time(org.ldk.structs.Option_u64Z val) { + bindings.PaymentParameters_set_expiry_time(this.ptr, val.ptr); Reference.reachabilityFence(this); Reference.reachabilityFence(val); + if (this != null) { this.ptrs_to.add(val); }; } /** - * Hints for routing to the payee, containing channels connecting the payee to public nodes. + * The maximum total CLTV delta we accept for the route. + * Defaults to [`DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA`]. */ - public RouteHint[] get_route_hints() { - long[] ret = bindings.PaymentParameters_get_route_hints(this.ptr); + public int get_max_total_cltv_expiry_delta() { + int ret = bindings.PaymentParameters_get_max_total_cltv_expiry_delta(this.ptr); Reference.reachabilityFence(this); - int ret_conv_11_len = ret.length; - RouteHint[] ret_conv_11_arr = new RouteHint[ret_conv_11_len]; - for (int l = 0; l < ret_conv_11_len; l++) { - long ret_conv_11 = ret[l]; - org.ldk.structs.RouteHint ret_conv_11_hu_conv = null; if (ret_conv_11 < 0 || ret_conv_11 > 4096) { ret_conv_11_hu_conv = new org.ldk.structs.RouteHint(null, ret_conv_11); } - ret_conv_11_hu_conv.ptrs_to.add(this); - ret_conv_11_arr[l] = ret_conv_11_hu_conv; - } - return ret_conv_11_arr; + return ret; } /** - * Hints for routing to the payee, containing channels connecting the payee to public nodes. + * The maximum total CLTV delta we accept for the route. + * Defaults to [`DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA`]. */ - public void set_route_hints(RouteHint[] val) { - bindings.PaymentParameters_set_route_hints(this.ptr, val != null ? Arrays.stream(val).mapToLong(val_conv_11 -> val_conv_11 == null ? 0 : val_conv_11.ptr & ~1).toArray() : null); + public void set_max_total_cltv_expiry_delta(int val) { + bindings.PaymentParameters_set_max_total_cltv_expiry_delta(this.ptr, val); Reference.reachabilityFence(this); Reference.reachabilityFence(val); } /** - * Expiration of a payment to the payee, in seconds relative to the UNIX epoch. + * The maximum number of paths that may be used by (MPP) payments. + * Defaults to [`DEFAULT_MAX_PATH_COUNT`]. */ - public Option_u64Z get_expiry_time() { - long ret = bindings.PaymentParameters_get_expiry_time(this.ptr); + public byte get_max_path_count() { + byte ret = bindings.PaymentParameters_get_max_path_count(this.ptr); Reference.reachabilityFence(this); - if (ret >= 0 && ret <= 4096) { return null; } - org.ldk.structs.Option_u64Z ret_hu_conv = org.ldk.structs.Option_u64Z.constr_from_ptr(ret); - ret_hu_conv.ptrs_to.add(this); - return ret_hu_conv; + return ret; } /** - * Expiration of a payment to the payee, in seconds relative to the UNIX epoch. + * The maximum number of paths that may be used by (MPP) payments. + * Defaults to [`DEFAULT_MAX_PATH_COUNT`]. */ - public void set_expiry_time(Option_u64Z val) { - bindings.PaymentParameters_set_expiry_time(this.ptr, val.ptr); + public void set_max_path_count(byte val) { + bindings.PaymentParameters_set_max_path_count(this.ptr, val); Reference.reachabilityFence(this); Reference.reachabilityFence(val); } /** - * The maximum total CLTV delta we accept for the route. - * Defaults to [`DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA`]. + * Selects the maximum share of a channel's total capacity which will be sent over a channel, + * as a power of 1/2. A higher value prefers to send the payment using more MPP parts whereas + * a lower value prefers to send larger MPP parts, potentially saturating channels and + * increasing failure probability for those paths. + * + * Note that this restriction will be relaxed during pathfinding after paths which meet this + * restriction have been found. While paths which meet this criteria will be searched for, it + * is ultimately up to the scorer to select them over other paths. + * + * A value of 0 will allow payments up to and including a channel's total announced usable + * capacity, a value of one will only use up to half its capacity, two 1/4, etc. + * + * Default value: 2 */ - public int get_max_total_cltv_expiry_delta() { - int ret = bindings.PaymentParameters_get_max_total_cltv_expiry_delta(this.ptr); + public byte get_max_channel_saturation_power_of_half() { + byte ret = bindings.PaymentParameters_get_max_channel_saturation_power_of_half(this.ptr); Reference.reachabilityFence(this); return ret; } /** - * The maximum total CLTV delta we accept for the route. - * Defaults to [`DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA`]. + * Selects the maximum share of a channel's total capacity which will be sent over a channel, + * as a power of 1/2. A higher value prefers to send the payment using more MPP parts whereas + * a lower value prefers to send larger MPP parts, potentially saturating channels and + * increasing failure probability for those paths. + * + * Note that this restriction will be relaxed during pathfinding after paths which meet this + * restriction have been found. While paths which meet this criteria will be searched for, it + * is ultimately up to the scorer to select them over other paths. + * + * A value of 0 will allow payments up to and including a channel's total announced usable + * capacity, a value of one will only use up to half its capacity, two 1/4, etc. + * + * Default value: 2 */ - public void set_max_total_cltv_expiry_delta(int val) { - bindings.PaymentParameters_set_max_total_cltv_expiry_delta(this.ptr, val); + public void set_max_channel_saturation_power_of_half(byte val) { + bindings.PaymentParameters_set_max_channel_saturation_power_of_half(this.ptr, val); + Reference.reachabilityFence(this); + Reference.reachabilityFence(val); + } + + /** + * A list of SCIDs which this payment was previously attempted over and which caused the + * payment to fail. Future attempts for the same payment shouldn't be relayed through any of + * these SCIDs. + * + * Returns a copy of the field. + */ + public long[] get_previously_failed_channels() { + long[] ret = bindings.PaymentParameters_get_previously_failed_channels(this.ptr); + Reference.reachabilityFence(this); + return ret; + } + + /** + * A list of SCIDs which this payment was previously attempted over and which caused the + * payment to fail. Future attempts for the same payment shouldn't be relayed through any of + * these SCIDs. + */ + public void set_previously_failed_channels(long[] val) { + bindings.PaymentParameters_set_previously_failed_channels(this.ptr, val); Reference.reachabilityFence(this); Reference.reachabilityFence(val); } /** - * The maximum number of paths that may be used by MPP payments. - * Defaults to [`DEFAULT_MAX_MPP_PATH_COUNT`]. + * A list of indices corresponding to blinded paths in [`Payee::Blinded::route_hints`] which this + * payment was previously attempted over and which caused the payment to fail. Future attempts + * for the same payment shouldn't be relayed through any of these blinded paths. + * + * Returns a copy of the field. */ - public byte get_max_mpp_path_count() { - byte ret = bindings.PaymentParameters_get_max_mpp_path_count(this.ptr); + public long[] get_previously_failed_blinded_path_idxs() { + long[] ret = bindings.PaymentParameters_get_previously_failed_blinded_path_idxs(this.ptr); Reference.reachabilityFence(this); return ret; } /** - * The maximum number of paths that may be used by MPP payments. - * Defaults to [`DEFAULT_MAX_MPP_PATH_COUNT`]. + * A list of indices corresponding to blinded paths in [`Payee::Blinded::route_hints`] which this + * payment was previously attempted over and which caused the payment to fail. Future attempts + * for the same payment shouldn't be relayed through any of these blinded paths. */ - public void set_max_mpp_path_count(byte val) { - bindings.PaymentParameters_set_max_mpp_path_count(this.ptr, val); + public void set_previously_failed_blinded_path_idxs(long[] val) { + bindings.PaymentParameters_set_previously_failed_blinded_path_idxs(this.ptr, val); Reference.reachabilityFence(this); Reference.reachabilityFence(val); } @@ -164,17 +197,20 @@ public class PaymentParameters extends CommonBase { /** * Constructs a new PaymentParameters given each field */ - public static PaymentParameters of(byte[] payee_pubkey_arg, InvoiceFeatures features_arg, RouteHint[] route_hints_arg, Option_u64Z expiry_time_arg, int max_total_cltv_expiry_delta_arg, byte max_mpp_path_count_arg) { - long ret = bindings.PaymentParameters_new(InternalUtils.check_arr_len(payee_pubkey_arg, 33), features_arg == null ? 0 : features_arg.ptr & ~1, route_hints_arg != null ? Arrays.stream(route_hints_arg).mapToLong(route_hints_arg_conv_11 -> route_hints_arg_conv_11 == null ? 0 : route_hints_arg_conv_11.ptr & ~1).toArray() : null, expiry_time_arg.ptr, max_total_cltv_expiry_delta_arg, max_mpp_path_count_arg); - Reference.reachabilityFence(payee_pubkey_arg); - Reference.reachabilityFence(features_arg); - Reference.reachabilityFence(route_hints_arg); + public static PaymentParameters of(org.ldk.structs.Payee payee_arg, org.ldk.structs.Option_u64Z expiry_time_arg, int max_total_cltv_expiry_delta_arg, byte max_path_count_arg, byte max_channel_saturation_power_of_half_arg, long[] previously_failed_channels_arg, long[] previously_failed_blinded_path_idxs_arg) { + long ret = bindings.PaymentParameters_new(payee_arg.ptr, expiry_time_arg.ptr, max_total_cltv_expiry_delta_arg, max_path_count_arg, max_channel_saturation_power_of_half_arg, previously_failed_channels_arg, previously_failed_blinded_path_idxs_arg); + Reference.reachabilityFence(payee_arg); Reference.reachabilityFence(expiry_time_arg); Reference.reachabilityFence(max_total_cltv_expiry_delta_arg); - Reference.reachabilityFence(max_mpp_path_count_arg); + Reference.reachabilityFence(max_path_count_arg); + Reference.reachabilityFence(max_channel_saturation_power_of_half_arg); + Reference.reachabilityFence(previously_failed_channels_arg); + Reference.reachabilityFence(previously_failed_blinded_path_idxs_arg); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } - ret_hu_conv.ptrs_to.add(ret_hu_conv); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(payee_arg); }; + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(expiry_time_arg); }; return ret_hu_conv; } @@ -192,12 +228,12 @@ public class PaymentParameters extends CommonBase { Reference.reachabilityFence(this); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } - ret_hu_conv.ptrs_to.add(this); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; return ret_hu_conv; } /** - * Checks if two PaymentParameterss contain equal inner contents. + * Generates a non-cryptographic 64-bit hash of the PaymentParameters. */ public long hash() { long ret = bindings.PaymentParameters_hash(this.ptr); @@ -213,11 +249,11 @@ public class PaymentParameters extends CommonBase { * This ignores pointers and is_owned flags and looks at the values in fields. * Two objects with NULL inner values will be considered "equal" here. */ - public boolean eq(PaymentParameters b) { - boolean ret = bindings.PaymentParameters_eq(this.ptr, b == null ? 0 : b.ptr & ~1); + public boolean eq(org.ldk.structs.PaymentParameters b) { + boolean ret = bindings.PaymentParameters_eq(this.ptr, b == null ? 0 : b.ptr); Reference.reachabilityFence(this); Reference.reachabilityFence(b); - this.ptrs_to.add(b); + if (this != null) { this.ptrs_to.add(b); }; return ret; } @@ -237,9 +273,10 @@ public class PaymentParameters extends CommonBase { /** * Read a PaymentParameters from a byte array, created by PaymentParameters_write */ - public static Result_PaymentParametersDecodeErrorZ read(byte[] ser) { - long ret = bindings.PaymentParameters_read(ser); + public static Result_PaymentParametersDecodeErrorZ read(byte[] ser, int arg) { + long ret = bindings.PaymentParameters_read(ser, arg); Reference.reachabilityFence(ser); + Reference.reachabilityFence(arg); if (ret >= 0 && ret <= 4096) { return null; } Result_PaymentParametersDecodeErrorZ ret_hu_conv = Result_PaymentParametersDecodeErrorZ.constr_from_ptr(ret); return ret_hu_conv; @@ -247,25 +284,68 @@ public class PaymentParameters extends CommonBase { /** * Creates a payee with the node id of the given `pubkey`. + * + * The `final_cltv_expiry_delta` should match the expected final CLTV delta the recipient has + * provided. */ - public static PaymentParameters from_node_id(byte[] payee_pubkey) { - long ret = bindings.PaymentParameters_from_node_id(InternalUtils.check_arr_len(payee_pubkey, 33)); + public static PaymentParameters from_node_id(byte[] payee_pubkey, int final_cltv_expiry_delta) { + long ret = bindings.PaymentParameters_from_node_id(InternalUtils.check_arr_len(payee_pubkey, 33), final_cltv_expiry_delta); Reference.reachabilityFence(payee_pubkey); + Reference.reachabilityFence(final_cltv_expiry_delta); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } - ret_hu_conv.ptrs_to.add(ret_hu_conv); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; return ret_hu_conv; } /** * Creates a payee with the node id of the given `pubkey` to use for keysend payments. + * + * The `final_cltv_expiry_delta` should match the expected final CLTV delta the recipient has + * provided. + * + * Note that MPP keysend is not widely supported yet. The `allow_mpp` lets you choose + * whether your router will be allowed to find a multi-part route for this payment. If you + * set `allow_mpp` to true, you should ensure a payment secret is set on send, likely via + * [`RecipientOnionFields::secret_only`]. + * + * [`RecipientOnionFields::secret_only`]: crate::ln::channelmanager::RecipientOnionFields::secret_only */ - public static PaymentParameters for_keysend(byte[] payee_pubkey) { - long ret = bindings.PaymentParameters_for_keysend(InternalUtils.check_arr_len(payee_pubkey, 33)); + public static PaymentParameters for_keysend(byte[] payee_pubkey, int final_cltv_expiry_delta, boolean allow_mpp) { + long ret = bindings.PaymentParameters_for_keysend(InternalUtils.check_arr_len(payee_pubkey, 33), final_cltv_expiry_delta, allow_mpp); Reference.reachabilityFence(payee_pubkey); + Reference.reachabilityFence(final_cltv_expiry_delta); + Reference.reachabilityFence(allow_mpp); + if (ret >= 0 && ret <= 4096) { return null; } + org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; + return ret_hu_conv; + } + + /** + * Creates parameters for paying to a blinded payee from the provided invoice. Sets + * [`Payee::Blinded::route_hints`], [`Payee::Blinded::features`], and + * [`PaymentParameters::expiry_time`]. + */ + public static PaymentParameters from_bolt12_invoice(org.ldk.structs.Bolt12Invoice invoice) { + long ret = bindings.PaymentParameters_from_bolt12_invoice(invoice == null ? 0 : invoice.ptr); + Reference.reachabilityFence(invoice); + if (ret >= 0 && ret <= 4096) { return null; } + org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(invoice); }; + return ret_hu_conv; + } + + /** + * Creates parameters for paying to a blinded payee from the provided blinded route hints. + */ + public static PaymentParameters blinded(TwoTuple_BlindedPayInfoBlindedPathZ[] blinded_route_hints) { + long ret = bindings.PaymentParameters_blinded(blinded_route_hints != null ? Arrays.stream(blinded_route_hints).mapToLong(blinded_route_hints_conv_37 -> blinded_route_hints_conv_37 != null ? blinded_route_hints_conv_37.ptr : 0).toArray() : null); + Reference.reachabilityFence(blinded_route_hints); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.PaymentParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.PaymentParameters(null, ret); } - ret_hu_conv.ptrs_to.add(ret_hu_conv); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; return ret_hu_conv; }