X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FChannelManager.java;fp=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FChannelManager.java;h=08381445eeb466ea5569c537d84e5f6b35bf017a;hb=2f0e19ab23f28c5c1bc11dc6bff24e156da3ec01;hp=6be766d4da2ad44824abb822aeefec39cfb4bdfe;hpb=ab07d4394be144b5e7eb123655031dba5349b849;p=ldk-java diff --git a/src/main/java/org/ldk/structs/ChannelManager.java b/src/main/java/org/ldk/structs/ChannelManager.java index 6be766d4..08381445 100644 --- a/src/main/java/org/ldk/structs/ChannelManager.java +++ b/src/main/java/org/ldk/structs/ChannelManager.java @@ -267,11 +267,11 @@ public class ChannelManager extends CommonBase { * will be accepted on the given channel, and after additional timeout/the closing of all * pending HTLCs, the channel will be closed on chain. * - * If we are the channel initiator, we will pay between our [`Background`] and - * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`Normal`] fee - * estimate. + * If we are the channel initiator, we will pay between our [`ChannelCloseMinimum`] and + * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`NonAnchorChannelFee`] + * fee estimate. * If our counterparty is the channel initiator, we will require a channel closing - * transaction feerate of at least our [`Background`] feerate or the feerate which + * transaction feerate of at least our [`ChannelCloseMinimum`] feerate or the feerate which * would appear on a force-closure transaction, whichever is lower. We will allow our * counterparty to pay as much fee as they'd like, however. * @@ -283,8 +283,8 @@ public class ChannelManager extends CommonBase { * channel. * * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis - * [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background - * [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal + * [`ChannelCloseMinimum`]: crate::chain::chaininterface::ConfirmationTarget::ChannelCloseMinimum + * [`NonAnchorChannelFee`]: crate::chain::chaininterface::ConfirmationTarget::NonAnchorChannelFee * [`SendShutdown`]: crate::events::MessageSendEvent::SendShutdown */ public Result_NoneAPIErrorZ close_channel(byte[] channel_id, byte[] counterparty_node_id) { @@ -306,8 +306,8 @@ public class ChannelManager extends CommonBase { * the channel being closed or not: * If we are the channel initiator, we will pay at least this feerate on the closing * transaction. The upper-bound is set by - * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`Normal`] fee - * estimate (or `target_feerate_sat_per_1000_weight`, if it is greater). + * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`NonAnchorChannelFee`] + * fee estimate (or `target_feerate_sat_per_1000_weight`, if it is greater). * If our counterparty is the channel initiator, we will refuse to accept a channel closure * transaction feerate below `target_feerate_sat_per_1000_weight` (or the feerate which * will appear on a force-closure transaction, whichever is lower). @@ -325,8 +325,7 @@ public class ChannelManager extends CommonBase { * channel. * * [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis - * [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background - * [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal + * [`NonAnchorChannelFee`]: crate::chain::chaininterface::ConfirmationTarget::NonAnchorChannelFee * [`SendShutdown`]: crate::events::MessageSendEvent::SendShutdown * * Note that shutdown_script (or a relevant inner pointer) may be NULL or all-0s to represent None @@ -498,10 +497,20 @@ public class ChannelManager extends CommonBase { * wait until you receive either a [`Event::PaymentFailed`] or [`Event::PaymentSent`] event to * determine the ultimate status of a payment. * + * # Requested Invoices + * + * In the case of paying a [`Bolt12Invoice`] via [`ChannelManager::pay_for_offer`], abandoning + * the payment prior to receiving the invoice will result in an [`Event::InvoiceRequestFailed`] + * and prevent any attempts at paying it once received. The other events may only be generated + * once the invoice has been received. + * * # Restart Behavior * * If an [`Event::PaymentFailed`] is generated and we restart without first persisting the - * [`ChannelManager`], another [`Event::PaymentFailed`] may be generated. + * [`ChannelManager`], another [`Event::PaymentFailed`] may be generated; likewise for + * [`Event::InvoiceRequestFailed`]. + * + * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice */ public void abandon_payment(byte[] payment_id) { bindings.ChannelManager_abandon_payment(this.ptr, InternalUtils.check_arr_len(payment_id, 32)); @@ -842,6 +851,10 @@ public class ChannelManager extends CommonBase { * with the current [`ChannelConfig`]. * Removing peers which have disconnected but and no longer have any channels. * Force-closing and removing channels which have not completed establishment in a timely manner. + * Forgetting about stale outbound payments, either those that have already been fulfilled + * or those awaiting an invoice that hasn't been delivered in the necessary amount of time. + * The latter is determined using the system clock in `std` and the highest seen block time + * minus two hours in `no-std`. * * Note that this may cause reentrancy through [`chain::Watch::update_channel`] calls or feerate * estimate fetches. @@ -1007,6 +1020,106 @@ public class ChannelManager extends CommonBase { return ret_hu_conv; } + /** + * Pays for an [`Offer`] using the given parameters by creating an [`InvoiceRequest`] and + * enqueuing it to be sent via an onion message. [`ChannelManager`] will pay the actual + * [`Bolt12Invoice`] once it is received. + * + * Uses [`InvoiceRequestBuilder`] such that the [`InvoiceRequest`] it builds is recognized by + * the [`ChannelManager`] when handling a [`Bolt12Invoice`] message in response to the request. + * The optional parameters are used in the builder, if `Some`: + * - `quantity` for [`InvoiceRequest::quantity`] which must be set if + * [`Offer::expects_quantity`] is `true`. + * - `amount_msats` if overpaying what is required for the given `quantity` is desired, and + * - `payer_note` for [`InvoiceRequest::payer_note`]. + * + * If `max_total_routing_fee_msat` is not specified, The default from + * [`RouteParameters::from_payment_params_and_value`] is applied. + * + * # Payment + * + * The provided `payment_id` is used to ensure that only one invoice is paid for the request + * when received. See [Avoiding Duplicate Payments] for other requirements once the payment has + * been sent. + * + * To revoke the request, use [`ChannelManager::abandon_payment`] prior to receiving the + * invoice. If abandoned, or an invoice isn't received in a reasonable amount of time, the + * payment will fail with an [`Event::InvoiceRequestFailed`]. + * + * # Privacy + * + * Uses a one-hop [`BlindedPath`] for the reply path with [`ChannelManager::get_our_node_id`] + * as the introduction node and a derived payer id for payer privacy. As such, currently, the + * node must be announced. Otherwise, there is no way to find a path to the introduction node + * in order to send the [`Bolt12Invoice`]. + * + * # Limitations + * + * Requires a direct connection to an introduction node in [`Offer::paths`] or to + * [`Offer::signing_pubkey`], if empty. A similar restriction applies to the responding + * [`Bolt12Invoice::payment_paths`]. + * + * # Errors + * + * Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link + * or if the provided parameters are invalid for the offer. + * + * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest + * [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity + * [`InvoiceRequest::payer_note`]: crate::offers::invoice_request::InvoiceRequest::payer_note + * [`InvoiceRequestBuilder`]: crate::offers::invoice_request::InvoiceRequestBuilder + * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice + * [`Bolt12Invoice::payment_paths`]: crate::offers::invoice::Bolt12Invoice::payment_paths + * [Avoiding Duplicate Payments]: #avoiding-duplicate-payments + */ + public Result_NoneBolt12SemanticErrorZ pay_for_offer(org.ldk.structs.Offer offer, org.ldk.structs.Option_u64Z quantity, org.ldk.structs.Option_u64Z amount_msats, org.ldk.structs.Option_StrZ payer_note, byte[] payment_id, org.ldk.structs.Retry retry_strategy, org.ldk.structs.Option_u64Z max_total_routing_fee_msat) { + long ret = bindings.ChannelManager_pay_for_offer(this.ptr, offer == null ? 0 : offer.ptr, quantity.ptr, amount_msats.ptr, payer_note.ptr, InternalUtils.check_arr_len(payment_id, 32), retry_strategy.ptr, max_total_routing_fee_msat.ptr); + Reference.reachabilityFence(this); + Reference.reachabilityFence(offer); + Reference.reachabilityFence(quantity); + Reference.reachabilityFence(amount_msats); + Reference.reachabilityFence(payer_note); + Reference.reachabilityFence(payment_id); + Reference.reachabilityFence(retry_strategy); + Reference.reachabilityFence(max_total_routing_fee_msat); + if (ret >= 0 && ret <= 4096) { return null; } + Result_NoneBolt12SemanticErrorZ ret_hu_conv = Result_NoneBolt12SemanticErrorZ.constr_from_ptr(ret); + if (this != null) { this.ptrs_to.add(offer); }; + if (this != null) { this.ptrs_to.add(quantity); }; + if (this != null) { this.ptrs_to.add(amount_msats); }; + if (this != null) { this.ptrs_to.add(payer_note); }; + if (this != null) { this.ptrs_to.add(retry_strategy); }; + if (this != null) { this.ptrs_to.add(max_total_routing_fee_msat); }; + return ret_hu_conv; + } + + /** + * Creates a [`Bolt12Invoice`] for a [`Refund`] and enqueues it to be sent via an onion + * message. + * + * The resulting invoice uses a [`PaymentHash`] recognized by the [`ChannelManager`] and a + * [`BlindedPath`] containing the [`PaymentSecret`] needed to reconstruct the corresponding + * [`PaymentPreimage`]. + * + * # Limitations + * + * Requires a direct connection to an introduction node in [`Refund::paths`] or to + * [`Refund::payer_id`], if empty. This request is best effort; an invoice will be sent to each + * node meeting the aforementioned criteria, but there's no guarantee that they will be + * received and no retries will be made. + * + * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice + */ + public Result_NoneBolt12SemanticErrorZ request_refund_payment(org.ldk.structs.Refund refund) { + long ret = bindings.ChannelManager_request_refund_payment(this.ptr, refund == null ? 0 : refund.ptr); + Reference.reachabilityFence(this); + Reference.reachabilityFence(refund); + if (ret >= 0 && ret <= 4096) { return null; } + Result_NoneBolt12SemanticErrorZ ret_hu_conv = Result_NoneBolt12SemanticErrorZ.constr_from_ptr(ret); + if (this != null) { this.ptrs_to.add(refund); }; + return ret_hu_conv; + } + /** * Gets a payment secret and payment hash for use in an invoice given to a third party wishing * to pay us. @@ -1279,7 +1392,7 @@ public class ChannelManager extends CommonBase { } /** - * Fetches the set of [`NodeFeatures`] flags which are provided by or required by + * Fetches the set of [`NodeFeatures`] flags that are provided by or required by * [`ChannelManager`]. */ public NodeFeatures node_features() { @@ -1292,7 +1405,7 @@ public class ChannelManager extends CommonBase { } /** - * Fetches the set of [`ChannelFeatures`] flags which are provided by or required by + * Fetches the set of [`ChannelFeatures`] flags that are provided by or required by * [`ChannelManager`]. */ public ChannelFeatures channel_features() { @@ -1305,7 +1418,7 @@ public class ChannelManager extends CommonBase { } /** - * Fetches the set of [`ChannelTypeFeatures`] flags which are provided by or required by + * Fetches the set of [`ChannelTypeFeatures`] flags that are provided by or required by * [`ChannelManager`]. */ public ChannelTypeFeatures channel_type_features() { @@ -1318,7 +1431,7 @@ public class ChannelManager extends CommonBase { } /** - * Fetches the set of [`InitFeatures`] flags which are provided by or required by + * Fetches the set of [`InitFeatures`] flags that are provided by or required by * [`ChannelManager`]. */ public InitFeatures init_features() { @@ -1343,6 +1456,19 @@ public class ChannelManager extends CommonBase { return ret_hu_conv; } + /** + * Constructs a new OffersMessageHandler which calls the relevant methods on this_arg. + * This copies the `inner` pointer in this_arg and thus the returned OffersMessageHandler must be freed before this_arg is + */ + public OffersMessageHandler as_OffersMessageHandler() { + long ret = bindings.ChannelManager_as_OffersMessageHandler(this.ptr); + Reference.reachabilityFence(this); + if (ret >= 0 && ret <= 4096) { return null; } + OffersMessageHandler ret_hu_conv = new OffersMessageHandler(null, ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + return ret_hu_conv; + } + /** * Serialize the ChannelManager object into a byte array which can be read by ChannelManager_read */